@teamblind-chorus/ui 1.1.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

@@ -10,7 +10,7 @@ Reverse index from natural-language intent to family + sub-component. Read *befo
 
 Each family declares `visualReuse: "open" | "locked"` in its `<family>.family.json`. The catalog respects that flag.
 
-- **Open (default, 28 families)** — `avatar-rail`, `badge`, `banner`, `bubble`, `button`, `carousel`, `chip`, `directory-list`, `divider`, `feed`, `header`, `list`, `metadata`, `nav-card`, `nav-list`, `navigation-bar`, `page-shell`, `pagination`, `profile-header`, `progress`, `side-sheet`, `skeleton`, `status-tag`, `suggestion-list`, `switch`, `tab-bar`, `tabs`, `thumbnail`. The intent table is the *first* suggestion, but the agent MAY reach for these on visual-fit grounds even when the brief's intent does not match the row verbatim — e.g. `<Feed>` as a generic article-card surface, `<Banner>` as a tonal aside outside a literal "notice", `<Carousel>` as any labelled editorial block. Anatomy invariants (slot grammar, token bindings, intrinsic geometry) still apply.
+- **Open (default, 30 families)** — `avatar-rail`, `badge`, `banner`, `bubble`, `button`, `carousel`, `chip`, `directory-list`, `divider`, `empty-state`, `feed`, `header`, `list`, `metadata`, `nav-card`, `nav-list`, `navigation-bar`, `page-shell`, `pagination`, `profile-header`, `progress`, `side-sheet`, `skeleton`, `spinner`, `status-tag`, `suggestion-list`, `switch`, `tab-bar`, `tabs`, `thumbnail`. The intent table is the *first* suggestion, but the agent MAY reach for these on visual-fit grounds even when the brief's intent does not match the row verbatim — e.g. `<Feed>` as a generic article-card surface, `<Banner>` as a tonal aside outside a literal "notice", `<Carousel>` as any labelled editorial block. Anatomy invariants (slot grammar, token bindings, intrinsic geometry) still apply.
 - **Locked (5 families)** — `dialog`, `bottom-sheet`, `toast`, `tooltip`, `form-field`. MUST only be used when the brief's intent matches a row. Their contract IS the interaction — focus trap, auto-dismiss, ARIA live region, form semantics, hover/focus trigger. Borrowing the visual shape without the role breaks behavior. Marked *(locked)* below.
 
 When in doubt: open families are recipes, locked families are rules.
@@ -71,13 +71,13 @@ When in doubt: open families are recipes, locked families are rules.
 | avatar-anchored rows (channels, DMs)         | `list / entry`           | `full-bleed`   |
 | drill-in rows with trailing chevron          | `list / standard` (or `/ entry`, `/ radio`) with `nav: true` | `full-bleed`   |
 | standalone drill-in card (single row)        | `nav-card`               | **`inline`**   |
-| expandable titled sections (FAQ, T&C)        | `accordion`              | `full-bleed`   |
+| expandable titled sections (FAQ, T&C)        | `list / accordion`       | `full-bleed`   |
 | authored content stream (posts, comments)    | `feed / feed`            | `full-bleed`   |
 | follow suggestions block (swipeable peek)    | `suggestion-list`        | `full-bleed`   |
 | follow directory (full vertical scroll)      | `directory-list`         | `full-bleed`   |
 | label-only nav list with chevron rows        | `nav-list`               | `full-bleed`   |
 
-**Disambiguate**: `feed` = authored content (author, body, footer). `list` = menus/settings/pickers (stacked rows, hairline divider). `nav-card` = a SINGLE drill-in row as its own bounded outlined card — reach for it when one drill-in needs to read as its own affordance, not one entry in a stack. `accordion` = stacked rows that EXPAND in place rather than drill-in — for short content the user opens to read (FAQ, T&C, expandable filter). `suggestion-list` = labelled swipeable block of follow-suggestions (channels, people, companies, topics — same anatomy). `directory-list` = the same row anatomy at the `large` (48) rung but rendered as a full vertical scroll (no pager) — reach for it when the surface should expose the whole follow-able set. `nav-list` = a labelled vertical list of label-only chevron rows; same wrapper-of-Header + List composition, but for route navigation rather than follow.
+**Disambiguate**: `feed` = authored content (author, body, footer). `list` = menus/settings/pickers (stacked rows, hairline divider). `nav-card` = a SINGLE drill-in row as its own bounded outlined card — reach for it when one drill-in needs to read as its own affordance, not one entry in a stack. `list / accordion` = stacked rows that EXPAND in place rather than drill-in — for short content the user opens to read (FAQ, T&C, expandable filter). `suggestion-list` = labelled swipeable block of follow-suggestions (channels, people, companies, topics — same anatomy). `directory-list` = the same row anatomy at the `large` (48) rung but rendered as a full vertical scroll (no pager) — reach for it when the surface should expose the whole follow-able set. `nav-list` = a labelled vertical list of label-only chevron rows; same wrapper-of-Header + List composition, but for route navigation rather than follow.
 
 ### Entity directory rows + author attribution
 
@@ -165,16 +165,18 @@ Each row resolves to a typed React component — `<FormField variant="search" pl
 
 | Intent                                                | Family + sub          |
 | ----------------------------------------------------- | --------------------- |
+| indeterminate sub-second load (no known ratio)         | `spinner`             |
 | in-flight content placeholder (mirrors content shape) | `skeleton`            |
+| surface with no data yet (empty feed / search / inbox) | `empty-state`        |
 | linear progress for a known long-running task          | `progress`            |
 
-**Disambiguate**: `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. `progress` = slim track for a *long-running, identifiable* task with a known ratio (upload, onboarding step, background sync). For sub-300ms or opaque waits use neither (a brief blank surface or a spinner reads better).
+**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. |
@@ -203,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. |
@@ -214,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.",
@@ -119,6 +119,25 @@
       },
       "note": "Underline persists."
     },
+    "focused": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.focus"
+      },
+      "focusRing": {
+        "composition": "inward",
+        "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.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 item is in; never via plain mouse click."
+    },
     "disabled": {
       "containerOpacity": "sys.state.disabled",
       "suppressUnderline": true,
@@ -134,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)"
@@ -152,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.family.json

@@ -7,7 +7,9 @@
     "inline notice",
     "supplementary context",
     "tonal aside",
-    "in-flow tip"
+    "in-flow tip",
+    "trailing text-button commit",
+    "accent tint with neutral body copy"
   ],
   "visualReuse": "open",
   "layoutInset": "inline",