@teamblind-chorus/ui 1.1.0 → 1.2.0

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,10 +165,12 @@ 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
 

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

@@ -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.focusInset"
+        },
+        "outerRing": {
+          "width": "sys.borderWidth.thin",
+          "color": "sys.color.focus"
+        }
+      },
+      "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,

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",

package/agents/components/banner/banner.md

@@ -2,7 +2,7 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/banner/banner.md`](../../../i18n/ko/schema/components/banner/banner.md)
 
-An in-body explanation block — a tinted card sitting within the reading flow with an optional heading line, a short paragraph, and an optional follow-through link. Four axes: **appearance** (`default` / `accent` / `destructive`), **outline** (`outlined` / none), **leading slot** (`icon` / `thumbnail` / none), **trailing slot** (`trailingIcon` / none).
+An in-body explanation block — a tinted card sitting within the reading flow with an optional heading line, a short paragraph, and an optional follow-through link. Five axes: **appearance** (`default` / `accent` / `destructive`), **foreground** (tonal, or `neutralBody` to lay the Default neutral text over the accent fill), **outline** (`outlined` / none), **leading slot** (`icon` / `thumbnail` / none), **trailing slot** (`trailingIcon` / `trailingAction` Text Button / none).
 
 **Reach for this when** a passage needs a brief aside the reader can scan or skip. **Skip when** the message demands a decision ([Dialog](../dialog/dialog.md) / [Bottom sheet](../bottom-sheet/bottom-sheet.md)) or confirms a recent user action ([Toast](../toast/toast.md)).
 
@@ -44,6 +44,25 @@ import { Banner } from '@teamblind-chorus/ui';
 </Banner>
 ```
 
+### Accent with 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).
+
+```preview
+banner/accent-neutral-body
+---
+import { Banner } from '@teamblind-chorus/ui';
+
+<Banner
+  appearance="accent"
+  neutralBody
+  title="Level up faster"
+  action={{ label: 'How levels work', href: '#level' }}
+>
+  Stay active in the community to level up and unlock more of what the app offers.
+</Banner>
+```
+
 ### 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.
@@ -136,6 +155,37 @@ import { ForwardCircleFillIcon } from '@teamblind-chorus/ui/icons';
 </Banner>
 ```
 
+### With trailing action (Text Button)
+
+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.
+
+```preview
+banner/with-trailing-action
+---
+import { Banner, Button } from '@teamblind-chorus/ui';
+import { ChevronRightIcon } from '@teamblind-chorus/ui/icons';
+
+// vertical 8 between sibling banners is the parent column's job (safe zone)
+<div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--sys-layout-stack-xs)' }}>
+  <Banner
+    appearance="accent"
+    trailingAction={(
+      <Button variant="text" appearance="accent" size="small" trailingIcon={<ChevronRightIcon />}>
+        Enable
+      </Button>
+    )}
+  >
+    Turn on notifications to hear back the moment someone replies.
+  </Banner>
+  <Banner
+    appearance="default"
+    trailingAction={<Button variant="text" size="small">Dismiss</Button>}
+  >
+    Stay active in the community to level up and unlock more of what the app offers.
+  </Banner>
+</div>
+```
+
 ### With 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.
@@ -163,6 +213,7 @@ Two appearances on the *emphasis* axis (plus `destructive` for errors). Banner c
 |---------------|---------------------------------------------------------------------------------------------|--------------------------------------------------------------------|----------------------------|------------------------------------------------------------------------------|
 | `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.          |
 
 ## Slots
@@ -175,6 +226,7 @@ Two appearances on the *emphasis* axis (plus `destructive` for errors). Banner c
 - **body** — explanation copy. `body.sm` / Regular / inherits container foreground. Required.
 - **action** *(optional)* — follow-through link below the body. `label.md` / Semibold / underlined.
 - **trailingIcon** *(optional)* — 16 × 16 glyph at the trailing edge, vertically centred against the container. Paints in `currentColor`.
+- **trailingAction** *(optional)* — a [Text Button](../button/text.md) at the trailing edge, vertically centred. Owns its own size + appearance; default the appearance to the banner's colour family. Takes precedence over `trailingIcon`.
 
 ## Anatomy
 
@@ -188,6 +240,7 @@ Two appearances on the *emphasis* axis (plus `destructive` for errors). Banner c
 | 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`. |
 | 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` |
 
 ## States
 

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

@@ -21,6 +21,13 @@
       "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."
     },
+    "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)."
+    },
     "title": {
       "type": "node",
       "optional": true,
@@ -46,6 +53,11 @@
       "optional": true,
       "description": "{ label, href? , onClick? } — a follow-through link rendered as a block child below the body."
     },
+    "trailingAction": {
+      "type": "node",
+      "optional": true,
+      "description": "A [Text Button](../button/text.md) (`<Button variant=\"text\">`) rendered at the container's trailing edge, vertically centered against the whole block (`align-self: center`). Distinct from `action` (a follow-through link below the body): `trailingAction` is a compact inline commit that sits beside the copy — Dismiss, Enable, Undo. The button keeps full control of its own `size` and `appearance` per the button/text spec; **by default pick the appearance whose color family matches the banner fill** 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. Override only when a denser rung (`size=\"small\"` / `\"xsmall\"`) or a different emphasis is deliberately wanted. The button also keeps its own `leadingIcon` / `trailingIcon` slots, so the commit can carry an in-button glyph (e.g. a trailing `ChevronRightIcon` on an *Enable* / *Continue* commit). Takes precedence over the banner-level `trailingIcon` when both are passed."
+    },
     "children": {
       "type": "node",
       "required": true,
@@ -104,6 +116,13 @@
       "accepts": [
         "icon"
       ]
+    },
+    "trailingAction": {
+      "required": false,
+      "description": "Trailing-edge slot hosting a Text Button (`<Button variant=\"text\">`). Footprint-preserving (`flex: 0 0 auto`) and vertically centered against the container (`align-self: center`). The Button owns its own size + appearance; default the appearance to the banner's color family (accent → `accent`, default → `default`, destructive → `destructive` flavor). Takes precedence over `trailingIcon`.",
+      "accepts": [
+        "button"
+      ]
     }
   },
   "sizing": {
@@ -149,7 +168,7 @@
       "foreground": "sys.color.onPrimaryContainer",
       "actionColor": "inherit",
       "outlineColor": "color-mix(sys.color.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."
+      "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",
@@ -161,9 +180,13 @@
   },
   "behavior": {
     "actionLink": "When present, renders as an <a> and accepts either href (browser navigation) or onClick (consumer-controlled). Underline persists at rest so the link reads as actionable inside the muted block.",
+    "trailingAction": "A `<Button variant=\"text\">` in the trailing slot is a real interactive control (not aria-hidden, unlike the trailing icon). It carries its own size + appearance per the button/text spec; the default appearance follows the banner's color family so the commit reads as part of the tinted block (accent → accent, default → default, destructive → destructive flavor). When both `trailingAction` and `trailingIcon` are passed, the action wins the slot.",
+    "neutralForeground": "`neutralBody` re-tones only the accent appearance: the container foreground becomes `onSurface` (title + body) and the action steps to `primary`, matching the Default appearance's foreground treatment. Ignored on `default` and `destructive`.",
     "role": "Container carries role='note' so screen readers announce the banner as an aside."
   },
   "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",
     "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)",

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

@@ -124,6 +124,25 @@
         "opacity": "sys.state.pressed"
       }
     },
+    "focused": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.focus"
+      },
+      "focusRing": {
+        "composition": "outward",
+        "layer": "::after overlay — position:absolute, inset:0, no reflow (DESIGN.md Focus ring composition)",
+        "innerCounterRing": {
+          "width": "sys.borderWidth.hairline",
+          "color": "sys.color.focusInset"
+        },
+        "outerRing": {
+          "width": "sys.borderWidth.thin",
+          "color": "sys.color.focus"
+        }
+      },
+      "note": "Keyboard-focus (:focus-visible) visual. Mirrors the `focusIndicator` block (the external-reader contract); kept here so spec-only renderers see focus in the states map. Composes over the lifecycle state the button is in; never via plain mouse click."
+    },
     "disabled": {
       "overlay": null,
       "containerOpacity": "sys.state.disabled",

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

@@ -79,6 +79,25 @@
         "color": "label",
         "opacity": "sys.state.pressed"
       }
+    },
+    "focused": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.focus"
+      },
+      "focusRing": {
+        "composition": "outward",
+        "layer": "::after overlay — position:absolute, inset:0, no reflow (DESIGN.md Focus ring composition)",
+        "innerCounterRing": {
+          "width": "sys.borderWidth.hairline",
+          "color": "sys.color.focusInset"
+        },
+        "outerRing": {
+          "width": "sys.borderWidth.thin",
+          "color": "sys.color.focus"
+        }
+      },
+      "note": "Keyboard-focus (:focus-visible) visual. Mirrors the `focusIndicator` block (the external-reader contract); kept here so spec-only renderers see focus in the states map. Composes over the lifecycle state the FAB is in; never via plain mouse click."
     }
   },
   "focusIndicator": {

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

@@ -128,6 +128,25 @@
         "opacity": "sys.state.pressed"
       }
     },
+    "focused": {
+      "overlay": {
+        "color": "icon",
+        "opacity": "sys.state.focus"
+      },
+      "focusRing": {
+        "composition": "outward",
+        "layer": "::after overlay — position:absolute, inset:0, no reflow (DESIGN.md Focus ring composition)",
+        "innerCounterRing": {
+          "width": "sys.borderWidth.hairline",
+          "color": "sys.color.focusInset"
+        },
+        "outerRing": {
+          "width": "sys.borderWidth.thin",
+          "color": "sys.color.focus"
+        }
+      },
+      "note": "Keyboard-focus (:focus-visible) visual. Mirrors the `focusIndicator` block (the external-reader contract); kept here so spec-only renderers see focus in the states map. Composes over the lifecycle state the button is in; never via plain mouse click."
+    },
     "disabled": {
       "overlay": null,
       "containerOpacity": "sys.state.disabled",

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

@@ -161,6 +161,25 @@
         "opacity": "sys.state.pressed"
       }
     },
+    "focused": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.focus"
+      },
+      "focusRing": {
+        "composition": "outward",
+        "layer": "::after overlay — position:absolute, inset:0, no reflow (DESIGN.md Focus ring composition)",
+        "innerCounterRing": {
+          "width": "sys.borderWidth.hairline",
+          "color": "sys.color.focusInset"
+        },
+        "outerRing": {
+          "width": "sys.borderWidth.thin",
+          "color": "sys.color.focus"
+        }
+      },
+      "note": "Keyboard-focus (:focus-visible) visual. Mirrors the `focusIndicator` block (the external-reader contract); kept here so spec-only renderers see focus in the states map. Composes over the lifecycle state the button is in; never via plain mouse click."
+    },
     "disabled": {
       "overlay": null,
       "containerOpacity": "sys.state.disabled",

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

@@ -166,6 +166,25 @@
         "opacity": "sys.state.pressed"
       }
     },
+    "focused": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.focus"
+      },
+      "focusRing": {
+        "composition": "outward",
+        "layer": "::after overlay — position:absolute, inset:0, no reflow (DESIGN.md Focus ring composition)",
+        "innerCounterRing": {
+          "width": "sys.borderWidth.hairline",
+          "color": "sys.color.focusInset"
+        },
+        "outerRing": {
+          "width": "sys.borderWidth.thin",
+          "color": "sys.color.focus"
+        }
+      },
+      "note": "Keyboard-focus (:focus-visible) visual. Mirrors the `focusIndicator` block (the external-reader contract); kept here so spec-only renderers see focus in the states map. Composes over the lifecycle state the button is in; never via plain mouse click."
+    },
     "disabled": {
       "overlay": null,
       "containerOpacity": "sys.state.disabled",

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

@@ -92,6 +92,25 @@
         "opacity": "sys.state.pressed"
       }
     },
+    "focused": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.focus"
+      },
+      "focusRing": {
+        "composition": "outward",
+        "layer": "::after overlay — position:absolute, inset:0, no reflow (DESIGN.md Focus ring composition)",
+        "innerCounterRing": {
+          "width": "sys.borderWidth.hairline",
+          "color": "sys.color.focusInset"
+        },
+        "outerRing": {
+          "width": "sys.borderWidth.thin",
+          "color": "sys.color.focus"
+        }
+      },
+      "note": "Keyboard-focus (:focus-visible) visual. Mirrors the `focusIndicator` block (the external-reader contract); kept here so spec-only renderers see focus in the states map. Composes over the lifecycle state the button is in; never via plain mouse click."
+    },
     "disabled": {
       "overlay": null,
       "containerOpacity": "sys.state.disabled",

package/agents/components/chip/filter.spec.json

@@ -92,6 +92,25 @@
         "opacity": "sys.state.pressed"
       }
     },
+    "focused": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.focus"
+      },
+      "focusRing": {
+        "composition": "outward",
+        "layer": "::after overlay — position:absolute, inset:0, no reflow (DESIGN.md Focus ring composition)",
+        "innerCounterRing": {
+          "width": "sys.borderWidth.hairline",
+          "color": "sys.color.focusInset"
+        },
+        "outerRing": {
+          "width": "sys.borderWidth.thin",
+          "color": "sys.color.focus"
+        }
+      },
+      "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 chip is in; never via plain mouse click."
+    },
     "disabled": {
       "overlay": null,
       "containerOpacity": "sys.state.disabled",

package/agents/components/chip/tag.spec.json

@@ -73,6 +73,25 @@
         "opacity": "sys.state.pressed"
       }
     },
+    "focused": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.focus"
+      },
+      "focusRing": {
+        "composition": "outward",
+        "layer": "::after overlay — position:absolute, inset:0, no reflow (DESIGN.md Focus ring composition)",
+        "innerCounterRing": {
+          "width": "sys.borderWidth.hairline",
+          "color": "sys.color.focusInset"
+        },
+        "outerRing": {
+          "width": "sys.borderWidth.thin",
+          "color": "sys.color.focus"
+        }
+      },
+      "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 chip is in; never via plain mouse click."
+    },
     "disabled": {
       "overlay": null,
       "containerOpacity": "sys.state.disabled",

package/agents/components/empty-state/empty-state.family.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "empty-state",
+  "name": "EmptyState",
+  "description": "No-data placeholder — the centered composition a surface paints when it has no content yet (an empty feed, a search with no results, a fresh inbox). Fills the space the real data would occupy with an optional monochrome illustration, a required headline, optional body copy, and an optional primary CTA that performs the one action that would fill the surface. Single-spec family. Distinct from `skeleton` (in-flight tonal placeholder for data that is loading) — EmptyState is the durable 'there is nothing here yet, here is how to start' surface.",
+  "useCases": [
+    "surface with no data yet",
+    "empty feed / inbox / list",
+    "search with no results",
+    "first-run / zero state",
+    "cleared / dismissed-everything state"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "inline",
+  "spec": "empty-state.md",
+  "usage": {
+    "note": "Headline is the `headline` prop (required); `body` is the `body` prop; the CTA is the `action` object ({ label, href?/onClick? }) which renders a default-size primary Button — there is NO `cta` slot to fill with your own button. Pass an icon node to `illustration`.",
+    "example": "<EmptyState illustration={<ChatIcon />} headline=\"No posts yet\" body=\"Conversations you start or join will appear here.\" action={{ label: 'Start a post', onClick: () => {} }} />"
+  },
+  "subcomponents": [
+    {
+      "slug": "empty-state",
+      "spec": "empty-state.spec.json",
+      "md": "empty-state.md",
+      "default": true
+    }
+  ]
+}

package/agents/components/empty-state/empty-state.md

@@ -0,0 +1,69 @@
+# EmptyState
+
+The centered composition a surface paints when it holds no data yet — an optional monochrome illustration, a required headline, optional body copy, and an optional primary CTA that performs the one action that fills the surface.
+
+**Reach for this when** a feed, list, inbox, or search result would otherwise paint blank — a fresh account's empty feed, a search returning nothing, a notifications surface with nothing unread. **Skip when** the data is still loading (use [Skeleton](../skeleton/skeleton.md) — an in-flight tonal placeholder) or when the message is a transient confirmation (use [Toast](../toast/toast.md)).
+
+**Layout inset.** inline — EmptyState ships no surface fill or chrome of its own and claims no page rail. It centers its column inside the host surface that would otherwise hold the data; the host supplies the surface tier and the bounding box. The surrounding inset is the host's responsibility.
+
+## Default
+
+The full composition — illustration, headline, body, and a primary CTA. Three lines of copy at most: what the surface is for, why it is empty, and the one action that fills it. The CTA is the surface's primary action, composed as a default-size primary [Button](../button/button.md).
+
+```preview
+empty-state/default
+---
+import { EmptyState } from '@teamblind-chorus/ui';
+import { ChatIcon } from '@teamblind-chorus/ui/icons';
+
+<EmptyState
+  illustration={<ChatIcon />}
+  headline="No posts yet"
+  body="Conversations you start or join will appear here."
+  action={{ label: 'Start a post', onClick: () => {} }}
+/>
+```
+
+## Use cases
+
+### Without illustration
+
+The illustration is optional — omit it for a tighter, text-led zero state where a glyph would add nothing. The headline still leads; the body and CTA follow the same stack rhythm.
+
+```preview
+empty-state/no-illustration
+---
+import { EmptyState } from '@teamblind-chorus/ui';
+
+<EmptyState
+  headline="No results"
+  body="No channels match that search. Try a different keyword."
+  action={{ label: 'Clear search', onClick: () => {} }}
+/>
+```
+
+## Slots
+
+- **container** — centered flex column holding the whole composition. `align-items: center`, `text-align: center`. No surface fill of its own. `role="status"` so the empty state is announced without yanking focus.
+- **illustration** *(optional)* — centered glyph / illustration above the headline. `ref.space.600` (48) box, painted monochrome in `sys.color.onSurfaceVariant`.
+- **headline** — required lead line. `sys.typo.heading.sm` / `sys.color.onSurface`.
+- **body** *(optional)* — supporting line below the headline. `sys.typo.body.sm` / `sys.color.onSurfaceVariant`.
+- **action** *(optional)* — the primary CTA, composed from the `action` object as a default-size primary [Button](../button/button.md). There is no free `cta` slot.
+
+## Anatomy
+
+| Slot         | Token bindings |
+|--------------|----------------|
+| container    | Centered flex column, `align-items: center`, `text-align: center`, no fill; `role="status"` |
+| illustration | `ref.space.600` (48 × 48) box, `sys.color.onSurfaceVariant` (`currentColor`), `sys.layout.stack.sm` (12) below it to the headline |
+| headline     | `sys.typo.heading.sm`, `sys.color.onSurface` |
+| body         | `sys.typo.body.sm`, `sys.color.onSurfaceVariant`, `sys.layout.stack.2xs` (4) above it from the headline |
+| action       | Default-size primary [Button](../button/button.md), `sys.layout.stack.md` (16) above it from the body |
+
+## Behavior
+
+- **Centered in the host.** The composition is centered block + inline inside the surface that would otherwise hold the data. EmptyState owns no surface fill — the host supplies the surface tier and bounding box.
+- **Headline required, the rest optional.** Only the headline is required. The illustration, body, and CTA fill in as the copy needs them.
+- **Three lines of copy, one action.** Headline + body read as at most three lines (what the surface is for · why it is empty · the one action that fills it). The CTA is that one action.
+- **CTA is composed, not slotted.** Pass `action={{ label, href?/onClick? }}` — EmptyState renders the default-size primary Button so the fill action always reads as primary.
+- **Not a loading state.** For data that is still arriving, reach for [Skeleton](../skeleton/skeleton.md); EmptyState is the durable no-data surface.