@teamblind-chorus/ui 1.2.0 → 2.0.0

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"
         }
       }
     }
@@ -138,11 +138,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."
@@ -157,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"
         }
       }
     }
@@ -171,11 +171,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."
@@ -190,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)"
   },

package/agents/components/button/text.md

@@ -20,9 +20,7 @@ import { Button } from '@teamblind-chorus/ui';
 <Button variant="text">Not now</Button>
 ```
 
-## Use cases
-
-### Accent
+## Accent
 
 Brand-blue label (`primary`) — the inline commit. Reach for `accent` when the button reads as a navigational link (*See all*, *Follow*, *View details*).
 
@@ -34,7 +32,7 @@ import { Button } from '@teamblind-chorus/ui';
 <Button variant="text" appearance="accent">Skip</Button>
 ```
 
-### On primary
+## On primary
 
 Always-white label on top of a `primary`-filled host (Tooltip `default`). Theme-stable.
 
@@ -46,7 +44,7 @@ import { Button } from '@teamblind-chorus/ui';
 <Button variant="text" appearance="onPrimary">Got it</Button>
 ```
 
-### Inverse
+## Inverse
 
 For inverse hosts (Toast, coach-mark, snackbar). Label paints `inverseOnSurface`; tokens flip with theme.
 
@@ -58,7 +56,7 @@ import { Button } from '@teamblind-chorus/ui';
 <Button variant="text" appearance="inverse">Undo</Button>
 ```
 
-### With leading icon
+## Leading icon
 
 16px (`sys.icon.md`) glyph before the label at 4px gap — fixed across rungs.
 
@@ -70,7 +68,7 @@ import { Button, ChevronLeftIcon } from '@teamblind-chorus/ui';
 <Button variant="text" leadingIcon={<ChevronLeftIcon />}>Back</Button>
 ```
 
-### With trailing icon
+## Trailing icon
 
 Destination glyph after the label — chevron-right *Continue*, external-link *Open in new tab*.
 
@@ -82,7 +80,7 @@ import { Button, ChevronRightIcon } from '@teamblind-chorus/ui';
 <Button variant="text" trailingIcon={<ChevronRightIcon />}>Continue</Button>
 ```
 
-### Dropdown
+## Dropdown
 
 Disclosure trigger: the label reads as the **current value**, the trailing chevron flips with state — `ChevronDownIcon` at rest, `ChevronUpIcon` while the menu is open. Pair `aria-haspopup` + `aria-expanded` on the trigger and portal the menu so it escapes any clipping ancestor; never freeze the chevron when the menu is open.
 
@@ -112,31 +110,31 @@ function Example() {
 }
 ```
 
-### Group
+## Focus ring
 
-Optical alignment means chrome-to-chrome gap **is** the visible label-to-label distance. Row gap: `medium`/`small` → 16px (`sys.layout.inline.xl`); `xsmall` → 12px (`sys.layout.inline.lg`).
+Standard ring.
 
 ```preview
-button/text/group
+button/text/focused
 ---
 import { Button } from '@teamblind-chorus/ui';
 
-<div style={{ display: 'inline-flex', gap: 'var(--sys-layout-inline-md)' }}>
-  <Button variant="text">Cancel</Button>
-  <Button variant="text" appearance="accent">Save</Button>
-</div>
+<Button variant="text" state="focused">Skip</Button>
 ```
 
-### Focus indicator
+## Group
 
-Standard ring.
+Optical alignment means chrome-to-chrome gap **is** the visible label-to-label distance. Row gap: `medium`/`small` → 16px (`sys.layout.inline.xl`); `xsmall` → 12px (`sys.layout.inline.lg`).
 
 ```preview
-button/text/focused
+button/text/group
 ---
 import { Button } from '@teamblind-chorus/ui';
 
-<Button variant="text" state="focused">Skip</Button>
+<div style={{ display: 'inline-flex', gap: 'var(--sys-layout-inline-md)' }}>
+  <Button variant="text">Cancel</Button>
+  <Button variant="text" appearance="accent">Save</Button>
+</div>
 ```
 
 ## Slots
@@ -151,10 +149,10 @@ A **destructive** flavor swaps the label to `error` across every appearance.
 
 | Appearance  | Background (rest) | Label color                       | When to reach for it                                                                 |
 |-------------|-------------------|-----------------------------------|--------------------------------------------------------------------------------------|
-| `default`   | `transparent`     | `sys.color.onSurfaceVariant`      | Base inline action — "Not now", secondary inline trail commits. |
-| `accent`    | `transparent`     | `sys.color.primary`               | Brand-blue inline commit — "Skip", "See all". One per row. |
-| `onPrimary` | `transparent`     | `sys.color.onPrimary`             | On a `primary`-filled host (Tooltip `default`). Theme-stable. |
-| `inverse`   | `transparent`     | `sys.color.inverseOnSurface`      | Inside an inverse host (Toast, coach-mark). |
+| `default`   | `transparent`     | `sys.color.text.subtle`      | Base inline action — "Not now", secondary inline trail commits. |
+| `accent`    | `transparent`     | `sys.color.background.primary`               | Brand-blue inline commit — "Skip", "See all". One per row. |
+| `onPrimary` | `transparent`     | `sys.color.text.onFill`             | On a `primary`-filled host (Tooltip `default`). Theme-stable. |
+| `inverse`   | `transparent`     | `sys.color.text.inverse`      | Inside an inverse host (Toast, coach-mark). |
 
 ## Sizes
 

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

@@ -100,26 +100,26 @@
     "default": {
       "background": "transparent",
       "border": null,
-      "label": "sys.color.onSurfaceVariant",
+      "label": "sys.color.text.subtle",
       "note": "The base neutral inline action — the canonical Text 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 commit affordance. Use sparingly — never two `accent` Text Buttons in the same row.",
       "linkAffordanceRecommendation": "Prefer `accent` whenever the Text Button reads as a **link affordance** — a section header's trailing 'See all' / 'See more', a card-header 'Follow', an inline 'View details' next to a body paragraph. Link-like affordances should carry chromatic emphasis so the navigational intent is unambiguous; `default` (onSurfaceVariant) is for quieter inline commits that should recede into the body copy. Override to `default` only when a parent surface (e.g. a busy chrome bar) already carries enough chromatic weight that an `accent` label would compete."
     },
     "onPrimary": {
       "background": "transparent",
       "border": null,
-      "label": "sys.color.onPrimary",
+      "label": "sys.color.text.onFill",
       "note": "Always-white label for use on top of a `primary`-filled host (e.g. the Tooltip `default` appearance). Both `primary` and `onPrimary` are theme-stable (blue / white in light and dark mode), so the label reads as white against the brand-blue fill in either theme — unlike `inverse`, which flips with the theme."
     },
     "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. The `inverseOnSurface` token FLIPS with the theme (white in light mode, dark in dark mode) — that's correct against the also-flipping `inverseSurface` host. When the host fill does NOT flip (e.g. a `primary`-filled Tooltip in `default` appearance), reach for `onPrimary` instead so the label stays white in both themes."
     }
   },
@@ -130,22 +130,22 @@
         "default": {
           "background": "transparent",
           "border": null,
-          "label": "sys.color.error"
+          "label": "sys.color.text.danger"
         },
         "accent": {
           "background": "transparent",
           "border": null,
-          "label": "sys.color.error"
+          "label": "sys.color.text.danger"
         },
         "onPrimary": {
           "background": "transparent",
           "border": null,
-          "label": "sys.color.error"
+          "label": "sys.color.text.danger"
         },
         "inverse": {
           "background": "transparent",
           "border": null,
-          "label": "sys.color.error"
+          "label": "sys.color.text.danger"
         }
       }
     }
@@ -176,11 +176,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."
@@ -195,16 +195,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/toggle.md

@@ -2,7 +2,7 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/button/toggle.md`](../../../i18n/ko/schema/components/button/toggle.md)
 
-Commit-and-record action — a Toolbar-footprint button with two states. **Inactive** invites the commit (`primary` fill); **active** records it (`transparent` fill + hairline `outlineVariant` outline).
+Commit-and-record action — a Toolbar-footprint button with two states. **Inactive** invites the commit (`primary` fill); **active** records it (`transparent` fill + hairline `border.default` outline).
 
 **Reach for this when** you need a reversible commit that persists across views — *Follow / Following*, *Subscribe / Subscribed*, *Join / Joined*. **Skip when** the action is one-shot ([Standard Button](./standard.md)), the row is a dense toolbar ([Toolbar Button](./toolbar.md)), or the toggle belongs to a filter set ([Filter Chip](../chip/filter.md)).
 
@@ -24,7 +24,7 @@ import { Button } from '@teamblind-chorus/ui';
 
 ## Active
 
-The committed form — `transparent` fill with hairline `outlineVariant` stroke. The transparent fill lets the button sit on any host surface tier (page `surface`, card `surfaceContainer`, raised `surfaceContainerHigh`) without re-painting a background that would clash with the host. Use the same element across both states and toggle the `active` flag; the consumer swaps the label text. Reports state via `aria-pressed`.
+The committed form — `transparent` fill with hairline `border.default` stroke. The transparent fill lets the button sit on any host surface tier (page `surface`, card `surfaceContainer`, raised `surfaceContainerHigh`) without re-painting a background that would clash with the host. Use the same element across both states and toggle the `active` flag; the consumer swaps the label text. Reports state via `aria-pressed`.
 
 ```preview
 button/toggle/active
@@ -36,9 +36,7 @@ import { Button } from '@teamblind-chorus/ui';
 </Button>
 ```
 
-## Use cases
-
-### With icon
+## Leading icon
 
 A check glyph on commit reinforces the active read. Inactive form stays glyph-less.
 
@@ -53,7 +51,7 @@ import { CheckedIcon } from '@teamblind-chorus/ui/icons';
 </Button>
 ```
 
-### Focus indicator
+## Focus ring
 
 Both forms take the same standard ring; below shows inactive. See [Focus ring composition](../../DESIGN.md#focus-ring-composition).
 
@@ -71,7 +69,7 @@ import { Button } from '@teamblind-chorus/ui';
 
 - **label** — accessible name. Required, single line. Consumer swaps the verb between states ("Follow" → "Following"); no auto-rewrite.
 - **leadingIcon** (optional) — context glyph before the label. Inherits colour via `currentColor` per the [family rule](./button.md#icon-colour-inheritance-family-wide).
-- **trailingIcon** (optional) — directional/destination glyph after the label. Same contract as [Toolbar Button](./toolbar.md#with-trailing-icon).
+- **trailingIcon** (optional) — directional/destination glyph after the label. Same contract as [Toolbar Button](./toolbar.md#trailing-icon).
 
 ## Sizes
 
@@ -93,8 +91,8 @@ A single visual variant — inactive/active is expressed as a state on the same
 
 | State        | Background                          | Border (always 1px `sys.borderWidth.hairline`)          | Label / icon color                | Notes                                                                |
 |--------------|-------------------------------------|---------------------------------------------------------|-----------------------------------|----------------------------------------------------------------------|
-| inactive     | `sys.color.primary`                 | `transparent`                                           | `sys.color.onPrimary`             | Brand-loud fill inviting commit. Border `transparent` but 1px width held so footprint never changes between states. |
-| active       | `transparent`                       | `sys.color.outlineVariant`                              | `sys.color.onSurface`             | Committed form — hairline-outlined ghost over whatever host surface the button sits on. Transparent fill records state without claiming attention or clashing with the host tier. |
+| inactive     | `sys.color.background.primary`                 | `transparent`                                           | `sys.color.text.onFill`             | Brand-loud fill inviting commit. Border `transparent` but 1px width held so footprint never changes between states. |
+| active       | `transparent`                       | `sys.color.border.default`                              | `sys.color.text.default`             | Committed form — hairline-outlined ghost over whatever host surface the button sits on. Transparent fill records state without claiming attention or clashing with the host tier. |
 
 ## States