@teamblind-chorus/ui 1.2.0 → 2.0.0

package/agents/LOVABLE.md

@@ -58,7 +58,7 @@ On *any* first message (full paste, truncated mid-stream, blank template, existi
 
 **Group for alignment, gap for rhythm:** one parent owns the inset, every child stretches to its content-box edge; vertical spacing is `gap: var(--sys-layout-stack-*)` on the shared parent, **never** `margin-top` per child. Mental check before JSX: *what is the family's `layoutInset`?*
 
-**Rail self-diagnostic:** before calling it "done", paste the console snippet from [`anti-patterns.md` § Rail self-diagnostic](anti-patterns.md) — it fails if any full-bleed child's left/right edge disagrees by >1px. Run with Dialog/BottomSheet open *and* closed. Misalignment → discard + regenerate.
+**Rail self-diagnostic:** before calling it "done", paste the console snippet from **§E Rail self-diagnostic** (below) — it fails if any full-bleed child's left/right edge disagrees by >1px. Run with Dialog/BottomSheet open *and* closed. Misalignment → discard + regenerate.
 
 ---
 
@@ -104,8 +104,6 @@ Don't abbreviate the bracketed evidence; don't post readiness if any file is unr
 | `patterns/<name>.md` | Per-screen recipe (intent / layout / tokens / components); PNG on GitHub, same slug. |
 | `tokens.usage.json` | Per-token `value`/`role`/`usedFor`/`notFor`/`pairsWith`/`allowedComponents`. **Read before composing.** |
 | `icons.json` | Icon manifest (name → keywords + aliases). Import from `…/ui/icons` by exact name. |
-| `compose.md` | Composition cheatsheet — spacing / color / type recipes + guardrails. **Skim before JSX.** |
-| `anti-patterns.md` | 18 failure shapes, wrong-vs-right. Output matching ❌ → regenerate. |
 | `AGENTS.md` | Hard agent contract (principles + hard rules). |
 | `DESIGN.md` | Token model & foundations. **~1300 lines — fetch by anchor only** (below). |
 
@@ -130,7 +128,7 @@ Patterns are layout-level ground truth (`.md` = textual contract, GitHub `.png`
 ### A.3 Component contract lookup (every component)
 
 The catalog says *which*; the contract says *how*. **Don't improvise props / slot names from the English name** — the binding is in `spec.json`.
-1. **Locate family + sub** via `manifest.json`; multi-sub families → match `useCases` in `family.json`. **Check `visualReuse`:** `"open"` (28) allows visual-fit pick; `"locked"` (5) is canonical-role only.
+1. **Locate family + sub** via `manifest.json`; multi-sub families → match `useCases` in `family.json`. **Check `visualReuse`:** `"open"` (30) allows visual-fit pick; `"locked"` (5) is canonical-role only.
 2. **Read `spec.json` fully** — props (type / default / allowed), slots (`accepts` / `rendersAs` / `intrinsic` vs content), `tokens`, and **`forbidden`** (the closed negative list). Hard-reject filter at JSX time.
 3. **Read `.md`** for when / why + anatomy invariants.
 4. **Honor slot kind.** `intrinsic:true` → component paints it, don't fill. `accepts:["thumbnail"]` → content is a Chorus component, not raw `<img>` / div.
@@ -179,7 +177,7 @@ A brief like *"convert this page to Chorus"* / *"replace this UI"* is a **presen
 ## B. Design principles
 
 1. **Chorus First** — start at `manifest.json` + `catalog.md`; never invent values from screenshot inference or generic libraries.
-2. **Extrapolate, don't fork** — respect anatomy invariants (slot grammar, sizing tokens, state contract), flex composition. `"open"` (28) may be picked on visual fit; `"locked"` (5) canonical-role only.
+2. **Extrapolate, don't fork** — respect anatomy invariants (slot grammar, sizing tokens, state contract), flex composition. `"open"` (30) may be picked on visual fit; `"locked"` (5) canonical-role only.
 3. **New surfaces stay token-true** — every color / spacing / type / radius / border-width / elevation resolves through tokens + DESIGN.md. **Component flexible, tokens never.**
 4. **Lego-block composition** — combine and extend Chorus Lego-style.
 5. **UX-pattern consistency** — Dialog / BottomSheet / Toast / Tooltip / FormField own focus trap / auto-dismiss / ARIA live / hover trigger / `<input>` semantics; never borrow for shape.
@@ -197,10 +195,10 @@ A brief like *"convert this page to Chorus"* / *"replace this UI"* is a **presen
 Full rules in the **★ Layout & Padding Contract** above. Quick ref: shell pays the gutter once → full-bleed siblings stretch edge-to-edge · negative-margin opt-out inside `bounded-surface` · `embedded={true}` for AvatarRail / SuggestionList / Tabs / List inside Carousel / Feed · group for alignment, `gap` (not `margin-top`) for rhythm · Banner / NavCard are `inline` with no outer margin (host owns the inset; vertical gap via parent `gap: var(--sys-layout-stack-xs)`).
 
 ### Per-component anatomy gotchas
-Each family's **`spec.json#forbidden`** is the authoritative negative list — read it before placing. High-frequency ones: `Toast` trailing Button must be `appearance="inverse"`; `Thumbnail` needs `outlined` off a clean `surface*` tier (cover / `*Container` / dark photo / overlap); `List variant="entry"` thumbnail is optional per row (drop it → label flush at the 16 rail; pure label-only nav stacks → `NavList`); `NavigationBar variant="sub"` trailing icon Button must be `size="large"` (=24); `Tooltip` never overrides `width`. Placeholder path is `/placeholder.png` (never rename; swap per `images.md`, full contract `AGENTS.md` #9).
+Each family's **`spec.json#forbidden`** is the authoritative negative list — read it before placing. High-frequency ones: `Toast` trailing Button must be `appearance="inverse"`; `Thumbnail` needs `outlined` off a clean `surface*` tier (cover / `*Container` / dark photo / overlap); `List variant="entry"` thumbnail is optional per row (drop it → label flush at the 16 rail; pure label-only nav stacks → `NavList`); `NavigationBar variant="sub"` trailing icon Button must be `size="large"` (=24); `Tooltip` never overrides `width`. Placeholder path is `/placeholder.png` (never rename; full contract `AGENTS.md` #9).
 
 ### Token strictness (no literals)
-- **Every** color / spacing / radius / border-width / typography / elevation resolves to a token — `var(--sys-*)` preferred, `var(--ref-*)` only when sys is absent, **no fallbacks** (`var(--sys-*, 16px)`). Typography applies a full rung via `className="sys-typo-<role>-<rung>"` (no `font:` shorthand token — it voids to a system font); spacing uses `sys.layout.*` (`inline` horizontal / `stack` vertical / `container` interior / `page` gutter). The per-axis raw→token map (`gap:6`→rung, `border:1px`→inset shadow, off-ladder radius, etc.) lives in **`compose.md`**; the wrong-vs-right shapes in **`anti-patterns.md`**.
+- **Every** color / spacing / radius / border-width / typography / elevation resolves to a token — `var(--sys-*)` preferred, `var(--ref-*)` only when sys is absent, **no fallbacks** (`var(--sys-*, 16px)`). Typography applies a full rung via `className="sys-typo-<role>-<rung>"` (no `font:` shorthand token — it voids to a system font); spacing uses `sys.layout.*` (`inline` horizontal / `stack` vertical / `container` interior / `page` gutter). The per-axis raw→token map applies (`gap:6`→nearest `stack`/`inline` rung, `border:1px`→inset shadow, off-ladder radius→nearest 4/8/12/16/full rung).
 - **Three authorized literal exceptions** (`DESIGN.md § Adapting Chorus`): (1) intrinsic geometry naming anatomy (Thumbnail 48px, icon 16px); (2) `calc()` token compositions; (3) structural `0` / `100%` / `auto`. Else → token call; no-token value → flag a "Chorus gap".
 - **Semantic glyph color → `sys.color.icon.*`** (`.muted` / `.yellow` / `.red` / `.blue` / `.green` / `.purple`), never `ref.palette.*`. On a tinted host (`primary` / `error` / `brand` / `*Container`) use that host's `on*` pair instead.
 
@@ -220,7 +218,7 @@ Each family's **`spec.json#forbidden`** is the authoritative negative list — r
 | avatar / logo / leading image | `Thumbnail` | requires `src` |
 | unread count / numeric pill | `Badge` | — |
 
-**`"locked"` families never leave their canonical role:** `Dialog` (confirmation), `BottomSheet` (action sheet), `SideSheet` (off-canvas drawer; `anchor="left"\|"right"`), `Toast` (transient confirmation), `Tooltip` (trigger hint), `FormField` (labeled field; `variant="input"\|"search"\|"select"`). The other 28 allow visual-fit reuse as long as anatomy invariants hold. Specialised families — `FeedAd`, `DirectoryList`, `NavList`, `SuggestionList`, `AvatarRail`, `Bubble`, `Divider` — see `catalog.md`.
+**`"locked"` families never leave their canonical role:** `Dialog` (confirmation), `BottomSheet` (action sheet), `SideSheet` (off-canvas drawer; `anchor="left"\|"right"`), `Toast` (transient confirmation), `Tooltip` (trigger hint), `FormField` (labeled field; `variant="input"\|"search"\|"select"`). The other 30 allow visual-fit reuse as long as anatomy invariants hold. Specialised families — `FeedAd`, `DirectoryList`, `NavList`, `SuggestionList`, `AvatarRail`, `Bubble`, `Divider` — see `catalog.md`.
 
 ### CTAs
 - **Primary commit:** `<Button>` (standard, filled). **"See all" / links:** `<Button variant="text" appearance="accent">`. **Icon-only:** `<Button variant="icon">`.
@@ -231,7 +229,7 @@ Each family's **`spec.json#forbidden`** is the authoritative negative list — r
 
 ### Images & thumbnails
 - Every avatar / logo / thumb / post media / banner illustration uses `<Thumbnail>` or the `thumbnail` slot — never icon-in-circle, letter-in-div, grey block, or raw `<img>`. `Feed` / `List variant="thumbnail"` / `SuggestionList` / `DirectoryList` thumbnails are **required** (`thumbnail:{src,alt}`, fallback `src:"/placeholder.png"`; omission forbidden by `spec.json#forbidden`).
-- **Fill order (full decision tree in `images.md`):** (1) real project asset; (2) clear, brand-safe subject → **generate and self-host** (image tool → upload → store the URL); (3) else `/placeholder.png` + one-line note. **Never paste a third-party stock URL** (unsplash / pexels) and never synthesize a real brand or person — a plausible fake is worse than an honest placeholder.
+- **Fill order:** (1) real project asset; (2) clear, brand-safe subject → **generate and self-host** (image tool → upload → store the URL); (3) else `/placeholder.png` + one-line note. **Never paste a third-party stock URL** (unsplash / pexels) and never synthesize a real brand or person — a plausible fake is worse than an honest placeholder.
 - **Keep Chorus calm** — near-monochromatic neutral + one restrained blue accent, desaturated single-subject; avoid saturated red/orange/yellow, busy collages, plasticky AI stock. Only `src` / `alt` change (never `style` / `className` to fight slot geometry); `alt` matches the subject, not the role.
 
 ### Tone-adjective disarming
@@ -245,7 +243,7 @@ Each family's **`spec.json#forbidden`** is the authoritative negative list — r
 
 ## D. Pre-flight checklist (before presenting — any hit → discard + regenerate)
 
-High-value gate; the full 18-shape audit is **`anti-patterns.md`**. Does NOT punish `"open"` families for visual-fit reuse.
+High-value gate covering the most common failure shapes. Does NOT punish `"open"` families for visual-fit reuse.
 
 - [ ] **Raw action** — `<button>` / `<a>` / styled `<div>` as a CTA; Text CTA without `appearance="accent"`; icons as text glyphs (`+`, `×`, `→`, `★`, `•`).
 - [ ] **Bordered-`<div>` instead of a family** — card → Carousel / Feed / Banner; list/stack → List; avatar / letter-in-div → `<Thumbnail src=…>`. `Feed` / `List thumbnail` / `SuggestionList` / `DirectoryList` row missing its `thumbnail` slot; `Tabs` given bare string children.
@@ -259,7 +257,38 @@ High-value gate; the full 18-shape audit is **`anti-patterns.md`**. Does NOT pun
 - [ ] **Bulk migration (§A.6)** — for an existing-project brief: migrated **> 1 screen in one pass**, presented a migrated screen without a **named rollback point + behavior verification**, or took a *sweeping* brief ("convert the whole app") as a batch license instead of a confirmed one-at-a-time screen list.
 - [ ] **Fixed bars scroll with the page** — missing the 100dvh + `<main>{min-height:0; overflow-y:auto}` contract (§A.4).
 
-Then run the **rail self-diagnostic** (snippet in `anti-patterns.md`). Misalignment → discard + regenerate.
+Then run the **rail self-diagnostic** (§E below). Misalignment → discard + regenerate.
+
+---
+
+## E. Rail self-diagnostic
+
+Visual alignment contracts are checkable. After rendering, paste this into the dev-preview browser console — it measures every full-bleed child's actual left/right edge and fails loudly if they disagree by >1px. Run it with `<Dialog>` / `<BottomSheet>` open *and* closed (full-bleed children inside a surface must share the surface's inner rail). **Misalignment → discard + regenerate.**
+
+```js
+(() => {
+  const sels = [
+    '.chorus-navigation-bar', '.chorus-tab-bar', '.chorus-tabs',
+    '.chorus-carousel', '.chorus-feed', '.chorus-feed-ad',
+    '.chorus-list', '.chorus-suggestion-list', '.chorus-directory-list',
+    '.chorus-nav-list', '.chorus-avatar-rail',
+  ];
+  const rows = sels.flatMap(sel =>
+    [...document.querySelectorAll(sel)].map(el => {
+      const r = el.getBoundingClientRect();
+      return { sel, left: Math.round(r.left), right: Math.round(window.innerWidth - r.right) };
+    })
+  );
+  if (!rows.length) { console.log('No full-bleed children on this page.'); return; }
+  const L = new Set(rows.map(r => r.left)), R = new Set(rows.map(r => r.right));
+  console.table(rows);
+  if (L.size > 1 || R.size > 1) {
+    console.error(`❌ Rail misalignment — left: [${[...L].join(', ')}], right: [${[...R].join(', ')}]. Every full-bleed child should share one rail. Fix per § Layout-Type & Padding Contract.`);
+  } else {
+    console.log(`✅ Rail aligned — left=${[...L][0]}px, right=${[...R][0]}px.`);
+  }
+})();
+```
 
 ---
 

package/agents/catalog.md

@@ -172,11 +172,11 @@ Each row resolves to a typed React component — `<FormField variant="search" pl
 
 **Disambiguate**: `spinner` = rotating arc for a *brief, indeterminate* wait (under ~1s, no measurable ratio) — a button submit, an inline action, a first-paint loader. Reserve one per view. `skeleton` = *in-flight* tonal block previewing where content will land. For loading data the host would otherwise paint as empty. NOT for empty states (no data yet) — those use illustration + body copy. `empty-state` = the durable *no-data* surface — a centered illustration + headline + body + one primary CTA, painted where the real content would go (an empty feed, a search with no results, a fresh inbox); reach for it instead of leaving a no-data surface blank. `progress` = slim track for a *long-running, identifiable* task with a known ratio (upload, onboarding step, background sync). Pick by what you know: nothing measurable → `spinner`; the content's shape → `skeleton`; no data yet → `empty-state`; a ratio → `progress`.
 
-## Shadcn / Lovable name translation
+## Shadcn name translation
 
 When an AI agent (or designer paging in from shadcn) reaches for a shadcn-named component, this is the Chorus surface to render. Direct React `export` aliases live in `packages/ui/src/index.js` where the name doesn't already collide (`Sheet`, `Drawer`, `Alert`, `Avatar`, `AppBar`, `BottomNav`); the table below covers the rest — including where Chorus splits one shadcn shape into multiple intent-bound surfaces.
 
-| Shadcn / Lovable name              | Chorus surface to render                                                            | Notes |
+| Shadcn name              | Chorus surface to render                                                            | Notes |
 |-----------------------------------|------------------------------------------------------------------------------------|-------|
 | `<Alert variant="default">`        | `<Banner appearance="default">`                                                     | Already aliased — `import { Alert } from '@teamblind-chorus/ui'`. |
 | `<Alert variant="destructive">`    | `<Banner appearance="destructive">`                                                 | Use the destructive appearance. |
@@ -205,7 +205,7 @@ When an AI agent (or designer paging in from shadcn) reaches for a shadcn-named
 
 These shadcn primitives have no Chorus equivalent and no on-pattern mobile substitution. When a brief demands one, **stop and flag a "Chorus gap"** — do NOT improvise a wrapper, re-introduce shadcn, or hardcode raw values. Maintainers add the missing family; agents wait or work around.
 
-| Shadcn / Lovable name | Mobile use case (when it WOULD be needed) | Status |
+| Shadcn name | Mobile use case (when it WOULD be needed) | Status |
 |-----------------------|--------------------------------------------|--------|
 | `<Calendar>` (date picker) | Birthday, schedule, calendar event picker.    | **Gap**. Workaround: pair `<FormField variant="select">` with native `<input type="date">` inside a `<BottomSheet>`; flag the gap. |
 | `<Chart>` (data viz)    | Analytics, finance, fitness charts.            | **Gap**. Workaround: external `recharts`/`chart.js`, but every color/typography MUST resolve through Chorus tokens (`var(--sys-*)`); flag the gap. |
@@ -216,7 +216,7 @@ These shadcn primitives have no Chorus equivalent and no on-pattern mobile subst
 
 These shadcn primitives are desktop-first or web-OS conventions Chorus deliberately omits because the mobile equivalent is a different shape. Agents MUST substitute the listed pattern instead of re-introducing the shadcn primitive.
 
-| Shadcn / Lovable name | Out of scope because | Mobile substitute |
+| Shadcn name | Out of scope because | Mobile substitute |
 |-----------------------|----------------------|--------------------|
 | `<Breadcrumb>`        | Mobile is deep-link / drill-in; no horizontal trail.            | `<NavigationBar variant="sub">` (back + title). |
 | `<Menubar>`           | Persistent app menubar is desktop chrome.                       | `<NavigationBar>` for top chrome + `<BottomSheet>` for action overflow. |

package/agents/components/avatar-rail/avatar-rail.md

@@ -29,9 +29,7 @@ import { AvatarRail } from '@teamblind-chorus/ui';
 />
 ```
 
-## Use cases
-
-### With overflow
+## Overflow
 
 When the rail carries more items than the container fits, it scrolls horizontally.
 
@@ -90,7 +88,7 @@ Container has no interactive state. Each item is a text-link affordance obeying
 | `pressed`  | `sys.state.pressed`        | Underline persists; pressed overlay tints. |
 | `disabled` | overlay suppressed         | Item at `sys.state.disabled` opacity; underline suppressed. |
 
-The trailing action is a `small` Text Button (rendered as `<a>` when `href` is set) — Text Button hover overlay + standard three-layer focus ring. Mirrors the Channel List header action; the only difference is the rung.
+The trailing action is a `small` Text Button (rendered as `<a>` when `href` is set) — Text Button hover overlay + standard single focus ring. Mirrors the Channel List header action; the only difference is the rung.
 
 ## Focus indicator
 

package/agents/components/avatar-rail/avatar-rail.spec.json

@@ -66,7 +66,7 @@
     }
   },
   "sizing": {
-    "containerFill": "sys.color.surface",
+    "containerFill": "sys.color.surface.default",
     "containerPaddingBlock": "sys.layout.container.sm",
     "containerPaddingInline": "sys.layout.container.md",
     "containerActionGap": "sys.layout.inline.xl",
@@ -75,11 +75,11 @@
     "itemAvatarLabelGap": "sys.layout.stack.xs",
     "avatarSize": 48,
     "labelTypo": "sys.typo.label.sm",
-    "labelColor": "sys.color.onSurface",
+    "labelColor": "sys.color.text.default",
     "labelMaxWidth": "ref.space.1000",
-    "trailingActionRendersAs": "Button variant='text' size='small' appearance='accent' — label paints in sys.color.primary via the Text Button accent token.",
+    "trailingActionRendersAs": "Button variant='text' size='small' appearance='accent' — label paints in sys.color.background.primary via the Text Button accent token.",
     "trailingActionTypo": "sys.typo.label.md",
-    "trailingActionColor": "sys.color.primary"
+    "trailingActionColor": "sys.color.text.link"
   },
   "itemProps": {
     "value": {
@@ -103,7 +103,7 @@
   "states": {
     "default": {
       "decoration": "none",
-      "label": "sys.color.onSurface"
+      "label": "sys.color.text.default"
     },
     "hovered": {
       "description": "1px same-color underline under the label. Color does not change — the underline is the affordance.",
@@ -129,11 +129,11 @@
         "layer": "::after/::before overlay — position:absolute, inset:0, inset box-shadow, no reflow (DESIGN.md Focus ring composition)",
         "innerCounterRing": {
           "width": "sys.borderWidth.hairline",
-          "color": "sys.color.focusInset"
+          "color": "sys.color.border.focused"
         },
         "outerRing": {
           "width": "sys.borderWidth.thin",
-          "color": "sys.color.focus"
+          "color": "sys.color.border.focused"
         }
       },
       "note": "Keyboard-focus (:focus-visible) visual. Mirrors the `focusIndicator` block (the external-reader contract); kept here so spec-only renderers see focus in the states map. Composes over the lifecycle state the item is in; never via plain mouse click."
@@ -153,12 +153,8 @@
       "opacity": "sys.state.focus"
     },
     "ring": {
-      "outerWidth": "sys.borderWidth.thin",
-      "outerColor": "sys.color.focus",
-      "outerLayerPosition": "depth 0..2px from the item edge (the outer stroke)",
-      "insetWidth": "sys.borderWidth.hairline",
-      "insetColor": "sys.color.focusInset",
-      "insetLayerPosition": "depth 2..3px from the item edge (the counter-ring just inside the outer stroke)",
+      "width": "sys.borderWidth.hairline",
+      "color": "sys.color.border.focused",
       "implementation": "inset box-shadow on the item's `::after` overlay. Constrained strictly inside the item's footprint and never exceeds it."
     },
     "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
@@ -171,7 +167,7 @@
     "trailingActionFloats": "The optional trailingAction stays at the end of the rail content; when the rail overflows, scrolling reveals it."
   },
   "forbidden": [
-    "rail item rendered with sys.color.brand as the fill — avatar-rail items inherit the underlying Thumbnail family contract",
+    "rail item rendered with sys.color.text.brand as the fill — avatar-rail items inherit the underlying Thumbnail family contract",
     "rail wrapped in a horizontal-padding div — avatar-rail is full-bleed by family declaration",
     "label below 12px — rail labels use sys.typo.label.sm (12px), never finer",
     "rail items reflowing — the rail snap-scrolls horizontally with a fixed item width"

package/agents/components/badge/role.md

@@ -20,11 +20,9 @@ import { Badge } from '@teamblind-chorus/ui';
 <Badge variant="role">Verified</Badge>
 ```
 
-## Use cases
+## Inverse
 
-### Inverse (PRO)
-
-`appearance="inverse"` swaps the fill to the high-contrast inverse pair (`sys.color.inverseSurface` / `sys.color.inverseOnSurface` — theme-aware, flips in dark mode). Reserved for **PRO**, the mark on paid professional users; never reach for it as a styling option on ordinary roles. Same geometry as default — only the fill pair changes.
+`appearance="inverse"` swaps the fill to the high-contrast inverse pair (`sys.color.background.inverse` / `sys.color.text.inverse` — theme-aware, flips in dark mode). Reserved for **PRO**, the mark on paid professional users; never reach for it as a styling option on ordinary roles. Same geometry as default — only the fill pair changes.
 
 ```preview
 badge/role/inverse
@@ -34,7 +32,7 @@ import { Badge } from '@teamblind-chorus/ui';
 <Badge variant="role" appearance="inverse">PRO</Badge>
 ```
 
-### Canonical labels
+## Canonical labels
 
 The product-canonical roles — **Channel owner** (채널장), **Verified** (현직자, the verified professional), and **PRO** (the paid professional, always on the inverse appearance). Labels display in English; any short role / title fits the same pill. Keep it to 1–2 words and one badge per person.
 
@@ -50,7 +48,7 @@ import { Badge } from '@teamblind-chorus/ui';
 </div>
 ```
 
-### With metadata
+## Metadata host
 
 The canonical host — the trailing **nickname** item of [Metadata](../metadata/metadata.md)'s meta row (second line; the nickname displays bare, no @ prefix). Pass the pill through the meta item's `badge` field so it renders after the nickname link, *outside* the `<a>` (4px `inline.sm` gap — never link content). The badge annotates the person the way the timestamp annotates the post. **Exactly one badge rides the nickname** — when a user qualifies for several roles, pick the contextually dominant one; never stack.
 
@@ -78,8 +76,8 @@ Two appearances on a single emphasis axis — both theme-aware, no separate dark
 
 | Appearance | Background | Label | Reserved for |
 |------------|------------|-------|--------------|
-| `default`  | `sys.color.primaryContainer` | `sys.color.onPrimaryContainer` | Ordinary role marks — Channel owner, Verified |
-| `inverse`  | `sys.color.inverseSurface`   | `sys.color.inverseOnSurface`   | The **PRO** paid-expert mark only |
+| `default`  | `sys.color.background.selected` | `sys.color.text.link` | Ordinary role marks — Channel owner, Verified |
+| `inverse`  | `sys.color.background.inverse`   | `sys.color.text.inverse`   | The **PRO** paid-expert mark only |
 
 Never the brand pair — brand on a badge is the [Update](./update.md) activity marker, and a brand-filled role mark would read as an alert.
 
@@ -93,7 +91,7 @@ Single rung.
 
 | Size   | Min-height / width     | Padding (block × inline)              | Label                                |
 |--------|------------------------|---------------------------------------|--------------------------------------|
-| medium | 16px (`ref.space.200`) | 2 × 6 (`ref.space.25` × `ref.space.75`) | 10 / Semibold (`sys.typo.caption`) |
+| medium | 16px (`ref.space.200`) | 2 × 6 (`ref.space.25` × `ref.space.75`) | 10 / Semibold (`sys.typo.label.xs`) |
 
 `ref.space.25` (2px) and `ref.space.75` (6px) bind raw because `sys.*` exposes no steps there — in lockstep with [Update](./update.md)'s rungs.
 

package/agents/components/badge/role.spec.json

@@ -3,7 +3,7 @@
   "name": "Badge",
   "family": "badge",
   "subcomponent": "role",
-  "description": "Role badge — a tonal primary-container pill naming a user's role or title, riding the bare nickname (no @ prefix) at the end of the user-metadata meta row. Labels display in English; canonical: 'Channel owner' (채널장), 'Verified' (현직자, the verified professional). Two appearances: `default` (pale `sys.color.primaryContainer` fill with `sys.color.onPrimaryContainer` label) and `inverse` (`sys.color.inverseSurface` / `sys.color.inverseOnSurface` — reserved for the PRO mark on paid professional users). Shared geometry, 10px (`caption`) text, 16-rung min-height, `radius.full` corner. Identity, not state: it says who the person *is* — for workflow state (pending / rejected / draft) reach for StatusTag instead. Presentational; never interactive. Reaches the meta row through Metadata's meta-item `badge` field so the pill renders outside the nickname's <a>.",
+  "description": "Role badge — a tonal primary-container pill naming a user's role or title, riding the bare nickname (no @ prefix) at the end of the user-metadata meta row. Labels display in English; canonical: 'Channel owner' (채널장), 'Verified' (현직자, the verified professional). Two appearances: `default` (pale `sys.color.background.selected` fill with `sys.color.text.link` label) and `inverse` (`sys.color.background.inverse` / `sys.color.text.inverse` — reserved for the PRO mark on paid professional users). Shared geometry, 10px (`caption`) text, 16-rung min-height, `radius.full` corner. Identity, not state: it says who the person *is* — for workflow state (pending / rejected / draft) reach for StatusTag instead. Presentational; never interactive. Reaches the meta row through Metadata's meta-item `badge` field so the pill renders outside the nickname's <a>.",
   "element": "span",
   "props": {
     "variant": {
@@ -35,15 +35,15 @@
   },
   "appearances": {
     "default": {
-      "background": "sys.color.primaryContainer",
-      "label": "sys.color.onPrimaryContainer",
+      "background": "sys.color.background.selected",
+      "label": "sys.color.text.link",
       "radius": "sys.radius.full",
       "default": true,
       "note": "Tonal informational pair — pale primary container fill with the deep primary-container label. Theme-aware sys tokens, so no separate dark binding. Never the brand pair: brand is reserved for the Update sub's activity marker, and a brand-filled role mark would read as an alert, not an identity."
     },
     "inverse": {
-      "background": "sys.color.inverseSurface",
-      "label": "sys.color.inverseOnSurface",
+      "background": "sys.color.background.inverse",
+      "label": "sys.color.text.inverse",
       "radius": "sys.radius.full",
       "note": "Inverse pair — the strongest mark in the row: near-black pill with light label (theme-aware; flips in dark mode). Reserved for the PRO mark on paid professional users. Same geometry as default; only the fill pair changes."
     }
@@ -54,7 +54,7 @@
       "minWidth": "ref.space.200",
       "paddingBlock": "ref.space.25",
       "paddingInline": "ref.space.75",
-      "labelTypo": "sys.typo.caption",
+      "labelTypo": "sys.typo.label.xs",
       "labelLineHeight": "1.2",
       "note": "Single 16-rung (`ref.space.200`) — sized to ride inline beside `caption`/`label` metadata text without stretching the row. 2 × 6 padding (`ref.space.25` × `ref.space.75`); the reference steps bind raw where `sys.*` exposes no step, in lockstep with the Update sub's rungs. Label line-height is the structural `1.2` (same device as StatusTag): 10px × 1.2 + 2 × 2px padding = exactly 16px — `caption`'s 15px running-text line would push the pill to 19."
     }

package/agents/components/badge/update.md

@@ -32,9 +32,7 @@ import { Badge } from '@teamblind-chorus/ui';
 <Badge size="dot-md" />
 ```
 
-## Use cases
-
-### Digit cases
+## Digit cases
 
 Single digit collapses to a circle (`min-width = min-height`); two digits stretch via `padding-inline`; counts past 99 cap at `99+`.
 
@@ -50,7 +48,7 @@ import { Badge } from '@teamblind-chorus/ui';
 </div>
 ```
 
-### On thumbnail
+## Thumbnail dot
 
 The canonical hosted form — Dot at a [Thumbnail](../thumbnail/thumbnail.md)'s top-right. Thumbnail picks `dot-md` at 32 / 40 / 48 and `dot-sm` at 16 / 20 / 24. The dot rides above the image without enlarging the bounding box.
 
@@ -62,7 +60,7 @@ import { Thumbnail } from '@teamblind-chorus/ui';
 <Thumbnail size={48} src="…" alt="Channel" updateDot />
 ```
 
-### On icon
+## Icon dot
 
 Dot painted at an icon's top-right (notification bell, chat, mention). Always `dot-sm` regardless of icon size — a 6 × 6 dot reads as a highlight against the icon's drawing area. The 2px `surface`-color outline keeps it discrete from the icon stroke; the icon's `icon.md` / `icon.lg` footprint never changes.
 
@@ -78,7 +76,7 @@ import { BellIcon } from '@teamblind-chorus/ui/icons';
 </span>
 ```
 
-### With host
+## List row host
 
 Numeric badge attached inside the label cell of a thumbnail `List` row — the canonical product use. Badge sits flush against the channel name (8px inline gap).
 
@@ -106,7 +104,7 @@ const labelWithBadge = (text, count) => (
 
 ## Appearance
 
-Single appearance — the **brand** token pair (`sys.color.brand` background, `sys.color.onBrand` label). Brand is one tonal step brighter than `error` and reserved for short-label attention pins. Do not reach for `error` or `brandContainer`.
+Single appearance — the **brand** token pair (`sys.color.text.brand` background, `sys.color.text.onFill` label). Brand is one tonal step brighter than `error` and reserved for short-label attention pins. Do not reach for `error` or `brandContainer`.
 
 ## Slots
 
@@ -119,7 +117,7 @@ Four rungs split across the two types — two per type. All rungs share `sys.rad
 | Type     | Size    | Min-height / width       | Padding (block × inline)                 | Label                                | Halo                       |
 |----------|---------|--------------------------|------------------------------------------|--------------------------------------|----------------------------|
 | Numeric  | medium  | 20px (`ref.space.250` ‡) | 0 × 6 (`0` × `ref.space.75` ‡)           | 12 / Semibold (`sys.typo.label.sm`)  | —                          |
-| Numeric  | small   | 16px (`ref.space.200`)   | 0 × 4 (`0` × `sys.layout.container.2xs`) | 10 / Semibold (`sys.typo.caption`) | —                          |
+| Numeric  | small   | 16px (`ref.space.200`)   | 0 × 4 (`0` × `sys.layout.container.2xs`) | 10 / Semibold (`sys.typo.label.xs`) | —                          |
 | Dot      | dot-md  | 8px (`ref.space.100`)    | 0 × 0                                    | — (labelless)                        | 2px `sys.color.surface` ⁋  |
 | Dot      | dot-sm  | 6px (`ref.space.75`)     | 0 × 0                                    | — (labelless)                        | 2px `sys.color.surface` ⁋  |
 

package/agents/components/badge/update.spec.json

@@ -58,11 +58,11 @@
     }
   },
   "appearance": {
-    "background": "sys.color.brand",
-    "label": "sys.color.onBrand",
+    "background": "sys.color.text.brand",
+    "label": "sys.color.text.onFill",
     "radius": "sys.radius.full",
     "dotOutline": {
-      "color": "sys.color.surface",
+      "color": "sys.color.surface.default",
       "width": "sys.borderWidth.thin",
       "rendering": "box-shadow",
       "note": "Update Dot rungs paint a 2px `surface`-color outline as a `box-shadow` so the dot stays a discrete chip on any host (image, icon, row) without enlarging its bounding box. The outline carves the dot out of whatever sits beside it; without it the brand fill blends into surrounding fills with similar luminance."
@@ -81,7 +81,7 @@
       "minWidth": "ref.space.200",
       "paddingBlock": "0",
       "paddingInline": "sys.layout.container.2xs",
-      "labelTypo": "sys.typo.caption"
+      "labelTypo": "sys.typo.label.xs"
     },
     "dot-md": {
       "minHeight": "ref.space.100",
@@ -106,7 +106,7 @@
     "overflow": "When the count overflows to '99+', the accessible name should read the intent (e.g. 'over 99 unread'), not the literal glyph."
   },
   "forbidden": [
-    "badge painted with sys.color.brand outside the HOT / NEW / unread-count canon — brand on a badge is the marker, not a tint",
+    "badge painted with sys.color.text.brand outside the HOT / NEW / unread-count canon — brand on a badge is the marker, not a tint",
     "badge rendered as a raw <span> with Tailwind — badge chrome owns the radius / padding / typography",
     "more than one badge on the same anchor — the host slot is single-badge by anatomy",
     "badge label below 12px (label.sm is the floor)"

package/agents/components/banner/banner.md

@@ -25,9 +25,7 @@ import { Banner } from '@teamblind-chorus/ui';
 </Banner>
 ```
 
-## Use cases
-
-### Accent
+## Accent
 
 The primary-tinted appearance. Body and action both paint in the primary family — reach for it when the aside should pull more attention.
 
@@ -44,9 +42,9 @@ import { Banner } from '@teamblind-chorus/ui';
 </Banner>
 ```
 
-### Accent with neutral body
+## Neutral body
 
-The `accent` fill kept, but the copy re-toned to the **Default** appearance's neutral foreground — title + body in `sys.color.onSurface`, action stepping to `sys.color.primary`. Pass `neutralBody`. This decouples the background tone from the text tone: the `primaryContainer` tint still pulls the eye, but the copy reads as quiet, high-legibility body text rather than tonal `onPrimaryContainer`. Reach for it on longer explainers or denser asides where primary-family body copy would tire the reader. No effect on `default` (already `onSurface`) or `destructive` (the warning tone must carry through the copy).
+The `accent` fill kept, but the copy re-toned to the **Default** appearance's neutral foreground — title + body in `sys.color.text.default`, action stepping to `sys.color.background.primary`. Pass `neutralBody`. This decouples the background tone from the text tone: the `primaryContainer` tint still pulls the eye, but the copy reads as quiet, high-legibility body text rather than tonal `onPrimaryContainer`. Reach for it on longer explainers or denser asides where primary-family body copy would tire the reader. No effect on `default` (already `onSurface`) or `destructive` (the warning tone must carry through the copy).
 
 ```preview
 banner/accent-neutral-body
@@ -63,7 +61,7 @@ import { Banner } from '@teamblind-chorus/ui';
 </Banner>
 ```
 
-### Destructive
+## Destructive
 
 The error-tinted appearance — `errorContainer` fill with `onErrorContainer` foreground. Reach for it when the aside is a blocking error or rejection (failed approvals, integration outages, billing). Use sparingly.
 
@@ -80,7 +78,7 @@ import { Banner } from '@teamblind-chorus/ui';
 </Banner>
 ```
 
-### With thumbnail
+## Thumbnail
 
 A leading [Thumbnail](../thumbnail/thumbnail.md) at the top-left — reach for it when the aside is anchored to a channel, author, or sub-brand image. Thumbnail owns its diameter and corner shape; the slot only top-aligns it next to the content column.
 
@@ -98,9 +96,9 @@ import { Banner, Thumbnail } from '@teamblind-chorus/ui';
 </Banner>
 ```
 
-### Outlined
+## Outlined
 
-An optional `sys.borderWidth.hairline` (1) inset stroke toned to the appearance's color family and kept deliberately faint, so the outline reads as a soft edge of the same tint rather than a frame — the subtle gray hairline (`sys.color.outlineVariant`) on `default`'s gray-tinted scrim, `primary` at 40% on `accent`'s blue-tinted container, `error` at 40% on `destructive`. Painted as an inset box-shadow, never a real border, so toggling it cannot change the banner's footprint. Reach for it when the tinted fill alone doesn't separate the banner from its host surface.
+An optional `sys.borderWidth.hairline` (1) inset stroke toned to the appearance's color family and kept deliberately faint, so the outline reads as a soft edge of the same tint rather than a frame — the subtle gray hairline (`sys.color.border.default`) on `default`'s gray-tinted scrim, `primary` at 40% on `accent`'s blue-tinted container, `error` at 40% on `destructive`. Painted as an inset box-shadow, never a real border, so toggling it cannot change the banner's footprint. Reach for it when the tinted fill alone doesn't separate the banner from its host surface.
 
 ```preview
 banner/outlined
@@ -118,7 +116,7 @@ import { Banner } from '@teamblind-chorus/ui';
 </div>
 ```
 
-### With title
+## Title
 
 An optional heading line above the body — `label.md` (14 / Semibold) in the container's foreground, separated from the body by `sys.layout.stack.2xs` (4) so the pair reads as one passage. Reach for it when the aside needs a scannable lead-in; omit it for single-thought asides where the body carries itself.
 
@@ -136,7 +134,7 @@ import { Banner } from '@teamblind-chorus/ui';
 </Banner>
 ```
 
-### With trailing icon
+## Trailing icon
 
 A 16 × 16 (`sys.icon.md`) glyph at the trailing edge, vertically centred against the whole block and painted in `currentColor`. Reach for it when the banner leads somewhere — a forward affordance such as `ForwardCircleFillIcon` signals the aside opens a destination.
 
@@ -155,7 +153,7 @@ import { ForwardCircleFillIcon } from '@teamblind-chorus/ui/icons';
 </Banner>
 ```
 
-### With trailing action (Text Button)
+## Trailing action
 
 A [Text Button](../button/text.md) (`<Button variant="text">`) in the trailing slot, vertically centred against the block — a compact inline commit beside the copy (*Dismiss*, *Enable*, *Undo*), distinct from `action` (the follow-through link below the body). The button keeps full control of its own `size` and `appearance` per the button/text spec, but **default the appearance to the banner's colour family** so the commit reads as part of the tinted block — `accent` banner → `appearance="accent"`, `default` banner → `appearance="default"`, `destructive` banner → the Text Button `destructive` flavor. It also keeps the button/text `leadingIcon` / `trailingIcon` slots, so the commit can carry an in-button glyph — e.g. a trailing `ChevronRightIcon` on a *Enable* / *Continue* commit. When both `trailingAction` and the banner-level `trailingIcon` are passed, the action wins the slot.
 
@@ -186,7 +184,7 @@ import { ChevronRightIcon } from '@teamblind-chorus/ui/icons';
 </div>
 ```
 
-### With icon
+## Icon
 
 A 16 × 16 (`sys.icon.md`) glyph at the leading edge, painted in `currentColor`. The slot is sized to the body's first-line height so the glyph centres on the first line — multi-line bodies keep the icon anchored to the first-line cap, not the block centre. Reach for it when the aside leads with a meaning-bearing glyph rather than a brand image.
 
@@ -211,10 +209,10 @@ Two appearances on the *emphasis* axis (plus `destructive` for errors). Banner c
 
 | Appearance    | Container fill                                                                              | Body / action color                                                | Outline (when `outlined`)  | When to use                                                                  |
 |---------------|---------------------------------------------------------------------------------------------|--------------------------------------------------------------------|----------------------------|------------------------------------------------------------------------------|
-| `default`     | `sys.color.scrimSubtle` (translucent inverse-tone scrim — ~8% black light / ~8% white dark) | body in `sys.color.onSurface`, action steps to `sys.color.primary` | `sys.color.outlineVariant` (subtle gray) | Supplementary asides the reader can pass over without missing the main flow. |
-| `accent`      | `sys.color.primaryContainer`                                                                | body in `onPrimaryContainer`, action inherits                      | `sys.color.primary` at 40% (soft blue)   | Asides worth pulling the eye toward — new-feature explainers, capability nudges. |
-| `accent` + `neutralBody` | `sys.color.primaryContainer`                                                     | title + body in `onSurface`, action steps to `sys.color.primary`   | `sys.color.primary` at 40% (soft blue)   | Accent tint pulls the eye, but the copy stays quiet, high-legibility body text — longer explainers, dense asides. |
-| `destructive` | `sys.color.errorContainer`                                                                  | body in `onErrorContainer`, action inherits                        | `sys.color.error` at 40%                 | Blocking errors or rejections — failed approvals, outages, billing.          |
+| `default`     | `sys.color.background.neutral` (translucent inverse-tone scrim — ~8% black light / ~8% white dark) | body in `sys.color.text.default`, action steps to `sys.color.background.primary` | `sys.color.border.default` (subtle gray) | Supplementary asides the reader can pass over without missing the main flow. |
+| `accent`      | `sys.color.background.selected`                                                                | body in `onPrimaryContainer`, action inherits                      | `sys.color.background.primary` at 40% (soft blue)   | Asides worth pulling the eye toward — new-feature explainers, capability nudges. |
+| `accent` + `neutralBody` | `sys.color.background.selected`                                                     | title + body in `onSurface`, action steps to `sys.color.background.primary`   | `sys.color.background.primary` at 40% (soft blue)   | Accent tint pulls the eye, but the copy stays quiet, high-legibility body text — longer explainers, dense asides. |
+| `destructive` | `sys.color.background.danger`                                                                  | body in `onErrorContainer`, action inherits                        | `sys.color.text.danger` at 40%                 | Blocking errors or rejections — failed approvals, outages, billing.          |
 
 ## Slots
 
@@ -238,7 +236,7 @@ Two appearances on the *emphasis* axis (plus `destructive` for errors). Banner c
 | content   | Flex column, `flex: 1 1 auto`, `sys.layout.stack.xs` (8) body↔action gap, `sys.layout.stack.2xs` (4) title↔body gap |
 | title     | `sys.typo.label.md` (14 / Semibold 600), color inherits |
 | body      | `sys.typo.body.sm` (14 / Regular), color inherits |
-| action    | `sys.typo.label.md` (14 / Semibold), underlined. Steps to `sys.color.primary` in `default`; inherits in `accent` / `destructive`. |
+| action    | `sys.typo.label.md` (14 / Semibold), underlined. Steps to `sys.color.background.primary` in `default`; inherits in `accent` / `destructive`. |
 | trailingIcon | `sys.icon.md` (16 × 16) glyph, `align-self: center` against the container, `color: currentColor` |
 | trailingAction | [Text Button](../button/text.md) (`<Button variant="text">`), `flex: 0 0 auto`, `align-self: center`. Size + appearance owned by the Button; default appearance to the banner's colour family. Wins the slot over `trailingIcon` |
 

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

@@ -19,14 +19,14 @@
       "type": "boolean",
       "optional": true,
       "default": false,
-      "description": "Paints a `sys.borderWidth.hairline` (1) inset stroke around the container, toned to the appearance's color family and kept deliberately faint so it reads as a soft edge of the same tint, not a frame — the subtle gray hairline (`sys.color.outlineVariant`) on `default`'s gray-tinted fill, `primary` at 40% (`color-mix(sys.color.primary, 40%)`) on `accent`'s blue-tinted fill, `error` at 40% on `destructive`. Rendered as an inset box-shadow, never a real border, so toggling it cannot change the banner's footprint (see DESIGN.md → Border & Stroke). Reach for it when the tinted fill alone doesn't separate the banner from its host surface."
+      "description": "Paints a `sys.borderWidth.hairline` (1) inset stroke around the container, toned to the appearance's color family and kept deliberately faint so it reads as a soft edge of the same tint, not a frame — the subtle gray hairline (`sys.color.border.default`) on `default`'s gray-tinted fill, `primary` at 40% (`color-mix(sys.color.background.primary, 40%)`) on `accent`'s blue-tinted fill, `error` at 40% on `destructive`. Rendered as an inset box-shadow, never a real border, so toggling it cannot change the banner's footprint (see DESIGN.md → Border & Stroke). Reach for it when the tinted fill alone doesn't separate the banner from its host surface."
     },
     "neutralBody": {
       "type": "boolean",
       "optional": true,
       "default": false,
       "appliesTo": "accent",
-      "description": "On `accent`, paints the title + body in the neutral default foreground (`sys.color.onSurface`) and steps the action to `sys.color.primary` — i.e. the **Default appearance's** foreground treatment laid over the accent fill, decoupling the background tone from the text tone. Reach for it when the `primaryContainer` tint should still pull the eye but the copy should read as quiet, high-legibility body text rather than tonal `onPrimaryContainer` primary-family text (long-form explainers, dense asides). No effect on `default` (already `onSurface`) or `destructive` (the warning tone must carry through the copy)."
+      "description": "On `accent`, paints the title + body in the neutral default foreground (`sys.color.text.default`) and steps the action to `sys.color.background.primary` — i.e. the **Default appearance's** foreground treatment laid over the accent fill, decoupling the background tone from the text tone. Reach for it when the `primaryContainer` tint should still pull the eye but the copy should read as quiet, high-legibility body text rather than tonal `onPrimaryContainer` primary-family text (long-form explainers, dense asides). No effect on `default` (already `onSurface`) or `destructive` (the warning tone must carry through the copy)."
     },
     "title": {
       "type": "node",
@@ -157,24 +157,24 @@
   },
   "appearances": {
     "default": {
-      "background": "sys.color.scrimSubtle",
-      "foreground": "sys.color.onSurface",
-      "actionColor": "sys.color.primary",
-      "outlineColor": "sys.color.outlineVariant",
-      "note": "Body sits in `onSurface`; the action link steps to primary so it carries the only chromatic emphasis. Background is the translucent inverse-tone scrim (`sys.color.scrimSubtle` — ~8% black light / ~8% white dark) so the banner stays harmonious on any underlying surface — body, raised card, BottomSheet, Dialog — by tinting one step darker (light mode) or lighter (dark mode) instead of pinning to a fixed neutral step that can collide with the surface ladder. Same scrim used by Chip / Tag default, Progress track, StatusTag neutral, and Skeleton."
+      "background": "sys.color.background.neutral",
+      "foreground": "sys.color.text.default",
+      "actionColor": "sys.color.text.link",
+      "outlineColor": "sys.color.border.default",
+      "note": "Body sits in `onSurface`; the action link steps to primary so it carries the only chromatic emphasis. Background is the translucent inverse-tone scrim (`sys.color.background.neutral` — ~8% black light / ~8% white dark) so the banner stays harmonious on any underlying surface — body, raised card, BottomSheet, Dialog — by tinting one step darker (light mode) or lighter (dark mode) instead of pinning to a fixed neutral step that can collide with the surface ladder. Same scrim used by Chip / Tag default, Progress track, StatusTag neutral, and Skeleton."
     },
     "accent": {
-      "background": "sys.color.primaryContainer",
-      "foreground": "sys.color.onPrimaryContainer",
+      "background": "sys.color.background.selected",
+      "foreground": "sys.color.text.link",
       "actionColor": "inherit",
-      "outlineColor": "color-mix(sys.color.primary, 40%)",
+      "outlineColor": "color-mix(sys.color.background.primary, 40%)",
       "note": "Both body and action paint in the primary family so the whole banner reads as one highlighted block. Reach for `accent` when the aside should pull more attention — feature explainers, capability nudges. Pass `neutralBody` to keep the accent fill but swap the copy to the Default appearance's neutral foreground (`onSurface` body, `primary` action) when the tint should pull the eye while the text stays quiet, high-legibility body copy."
     },
     "destructive": {
-      "background": "sys.color.errorContainer",
-      "foreground": "sys.color.onErrorContainer",
+      "background": "sys.color.background.danger",
+      "foreground": "sys.color.text.danger",
       "actionColor": "inherit",
-      "outlineColor": "color-mix(sys.color.error, 40%)",
+      "outlineColor": "color-mix(sys.color.text.danger, 40%)",
       "note": "Body and action paint in the error family so the whole banner reads as one warning block. Reach for `destructive` when the aside is a blocking error or rejection — failed approvals, integration outages, billing problems. Use sparingly — every destructive banner on a screen competes with the others for the user's alarm budget."
     }
   },
@@ -187,7 +187,7 @@
   "forbidden": [
     "banner trailing-edge commit rendered as a raw <a> / <button> or a filled/outlined Button — the trailing action is button/text, defaulted to the banner's color family",
     "neutralBody applied to default or destructive — it only decouples the accent fill from its foreground; default is already onSurface and destructive must carry the warning tone through the copy",
-    "default banner background painted with sys.color.brandContainer — informational banners use sys.color.primaryContainer; promotional banners use sys.color.surfaceContainerLow",
+    "default banner background painted with a brand-tinted fill — informational banners use sys.color.background.selected; promotional banners use sys.color.surface.sunken",
     "banner thumbnail slot omitted when banner role carries imagery — empty image area is forbidden, fall back to /placeholder.png",
     "banner used for transient confirmations — that role is the `toast` family (locked)",
     "banner CTA rendered as raw <a> / <button> — use button/text inside the action slot",