@teamblind-chorus/ui 1.0.1 → 1.2.0

package/agents/anti-patterns.md

@@ -1,6 +1,6 @@
 # anti-patterns.md — common Lovable / agent failure modes
 
-A catalogue of the wrong-shaped output Chorus consumers most often produce, paired with the right-shaped fix. Each entry names the rule, the broken snippet, and the corrected one. **Read at least once before composing a new screen** — most agent violations come from these ~16 recurring shapes. Pair with [`compose.md`](compose.md) and [`tokens.usage.json`](tokens.usage.json).
+A catalogue of the wrong-shaped output Chorus consumers most often produce, paired with the right-shaped fix. Each entry names the rule, the broken snippet, and the corrected one. **Read at least once before composing a new screen** — most agent violations come from these 18 recurring shapes. Pair with [`compose.md`](compose.md) and [`tokens.usage.json`](tokens.usage.json).
 
 When in doubt: if your output matches a "❌ wrong" snippet below, discard and regenerate.
 
@@ -383,7 +383,7 @@ The cognitive trap: *"No Chorus family fits a hint card / inline annotation / sm
 
 **Off-scale = pick the next ladder rung, NOT halfway.** 13px is forbidden; 12 or 14 are tokens. 6px gap is forbidden; 4 or 8 are tokens. If no token feels right, that's a Chorus gap report ("`spacing.inline.xs` reads too tight, `inline.sm` too loose for this slot — proposing a new rung") — not a license to invent. See the full raw → token map in [compose.md § When you go custom](compose.md).
 
-Side note: this entry catches the values. Whether you should have gone custom at all is a separate question — the visual-reuse table in [LOVABLE.md §C](LOVABLE.md) covers 13 `"open"` families that you can borrow on visual-fit grounds (`<Feed>` as a generic article-card surface, `<Section>` as any labelled block). Reach for that first; #14 only fires after you've genuinely exhausted the LEGO ladder.
+Side note: this entry catches the values. Whether you should have gone custom at all is a separate question — the visual-reuse table in [LOVABLE.md §C](LOVABLE.md) covers the `"open"` families that you can borrow on visual-fit grounds (`<Feed>` as a generic article-card surface, `<Section>` as any labelled block). Reach for that first; #14 only fires after you've genuinely exhausted the LEGO ladder.
 
 ---
 

package/agents/catalog.md

@@ -1,5 +1,7 @@
 # Catalog — intent → component
 
+> 🇰🇷 한국어: [`i18n/ko/schema/catalog.md`](../i18n/ko/schema/catalog.md)
+
 Reverse index from natural-language intent to family + sub-component. Read *before* opening any spec to narrow candidates. Authoritative shape lives in `schema/components/<family>/<sub>.spec.json`; this file is a routing layer.
 
 > **How to import / use a family → `usage.json`.** This catalog names families as `family / sub`. The React access pattern differs per family: a named import (`profile-header` → `import { ProfileHeader }`), a `variant=` prop (`button / fab` → `<Button variant="fab">` — there is **no** `<Fab>` export), a separate export (`carousel / post` → `PostCarousel`), or a data array (`list / entry` → `<List items={[…]}>` — there is **no** `<ListItem>`). `usage.json` is the authoritative, build-time **parity-checked** map of every family to its exact usage. **A failed `import { X }` for one component never means the catalog is unreliable or a family is "missing at runtime" — look it up in `usage.json` and use the access it specifies. Never fall back to assembling a family from token primitives.**
@@ -8,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, 27 families)** — `avatar-rail`, `badge`, `banner`, `bubble`, `button`, `carousel`, `chip`, `directory-list`, `divider`, `feed`, `header`, `list`, `metadata`, `nav-card`, `nav-list`, `navigation-bar`, `page-shell`, `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.
@@ -41,8 +43,9 @@ When in doubt: open families are recipes, locked families are rules.
 | reversible state (mute/unmute, follow)     | `button / toggle`             |
 | dense action inside a toolbar              | `button / toolbar`            |
 | destructive primary commit                 | `button / standard` with `flavor: "destructive"` (inside a Dialog) |
+| grouped buttons / docked bottom action bar | `button / group` → `<ButtonGroup>` (named export) |
 
-**Disambiguate**: FAB = the **single** canonical commit per screen. Destructive primary commits go in `dialog`/`bottom-sheet`, not on a FAB.
+**Disambiguate**: FAB = the **single** canonical commit per screen. Destructive primary commits go in `dialog`/`bottom-sheet`, not on a FAB. **Two or more Buttons that belong together** (Cancel + Save, or a bottom-pinned action bar) go in `<ButtonGroup>` — a **named export**, not `<Button variant="group">`. Use `variant="docked"` for the bottom action bar (full-bleed surface + 16px inset + 8px gap + upward `sys.elevation.sheet` shadow + optional `label`); never hand-roll the wrapper div or give it a top border. Like the other bars it renders in flow — `page-shell` owns the pinning.
 
 ## Structure & layout
 
@@ -68,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
 
@@ -152,8 +155,9 @@ Each row resolves to a typed React component — `<FormField variant="search" pl
 | instant-commit on/off toggle                 | `switch`          |
 | inline status mark next to a row label       | `status-tag`      |
 | always-on annotation pill anchored to a UI element | `bubble`     |
+| dot position indicator under a snap pager    | `pagination`      |
 
-**Disambiguate**: `switch` = single binary on/off that commits the moment it flips (notifications, privacy). For multi-option pickers use `list / radio`; for actions needing confirmation use `button` + `dialog`; for "selected" facet state in a chip row use `chip / filter`. `status-tag` = SMALL (16-rung, 10px text) decorative status pill inline next to a row label — "pending", "rejected", "draft". For a 32-rung interactive chip use `chip / tag`; for a numeric count attached to an icon/thumbnail use `badge / update`; for a role / title mark beside a user's nickname (Channel owner / Verified / PRO) use `badge / role` — identity, where `status-tag` is workflow state. `bubble` = a labelled pill with a tail that points at a specific element to flag attention *at rest* (new-feature nudge, keyword/campaign promo next to a top-bar icon or search bar) — vs `badge` (numeric count / dot, no tail) and `status-tag` (status mark on a row label).
+**Disambiguate**: `switch` = single binary on/off that commits the moment it flips (notifications, privacy). For multi-option pickers use `list / radio`; for actions needing confirmation use `button` + `dialog`; for "selected" facet state in a chip row use `chip / filter`. `status-tag` = SMALL (16-rung, 10px text) decorative status pill inline next to a row label — "pending", "rejected", "draft". For a 32-rung interactive chip use `chip / tag`; for a numeric count attached to an icon/thumbnail use `badge / update`; for a role / title mark beside a user's nickname (Channel owner / Verified / PRO) use `badge / role` — identity, where `status-tag` is workflow state. `bubble` = a labelled pill with a tail that points at a specific element to flag attention *at rest* (new-feature nudge, keyword/campaign promo next to a top-bar icon or search bar) — vs `badge` (numeric count / dot, no tail) and `status-tag` (status mark on a row label). `pagination` = decorative dot position row under a one-page-at-a-time pager (carousel, gallery) — non-interactive (`aria-hidden`), the host owns the active index; for tap-to-switch sections use `tabs`, for task-completion ratio use `progress`.
 
 ## Loading & Placeholder
 
@@ -161,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.md

@@ -1,5 +1,7 @@
 # Avatar rail
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/avatar-rail/avatar-rail.md`](../../../i18n/ko/schema/components/avatar-rail/avatar-rail.md)
+
 A horizontal strip of channel entry points — each item routes to a channel or company page. Composes a [Thumbnail](../thumbnail/thumbnail.md) (optional `updateDot`) and a single-line label; an optional trailing action lives at the end.
 
 **Reach for this when** the row is a label-only nav strip of subscribed or saved entities — *Subscribed channels*, *Saved companies*, *My topics*. **Skip when** rows carry follower counts or descriptions (use [DirectoryList](../directory-list/directory-list.md) / [SuggestionList](../suggestion-list/suggestion-list.md)), the surface is fixed-width profile cards ([Profile carousel](../carousel/profile.md)), or rows commit in place rather than route ([Toggle Button](../button/toggle.md) cluster).

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/badge/badge.md

@@ -1,5 +1,7 @@
 # Badge
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/badge/badge.md`](../../../i18n/ko/schema/components/badge/badge.md)
+
 A small, non-interactive mark anchored to a host label — badge-shaped annotation for two roles. **Update** is the brand-tone activity indicator: a numeric count pill or a labelless corner dot flagging unread / new activity (3 unread, `99+`, a dot on a [Thumbnail](../thumbnail/thumbnail.md)). **Role** is the tonal identity pill: a pale `primaryContainer` mark naming the user's role or title — Channel owner (채널장), Verified (현직자) — riding the bare nickname at the end of their metadata's meta row. The two share the anchored anatomy, the `radius.full` corner, and the never-interactive contract; they diverge on tone (brand vs primary-container) and on what they say about the host (*what's new* vs *who this is*). Both are reached through the single `Badge` export — `variant="update"` (default) / `variant="role"`.
 
 **Layout inset.** `inline` — slot atom. A Badge has no page-rail responsibility; the host places it (Thumbnail corner, List row label, [Metadata](../metadata/metadata.md) trailing edge). Never a sibling of `full-bleed` page rows.

package/agents/components/badge/role.md

@@ -1,5 +1,7 @@
 # Role
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/badge/role.md`](../../../i18n/ko/schema/components/badge/role.md)
+
 A tonal identity pill naming a user's role or title — anchored at the trailing edge of their metadata. Pale `primaryContainer` fill with a deep `onPrimaryContainer` label: informational, quiet, and clearly distinct from the [Update](./update.md) sub's brand-tone alert. Always rides beside a user identity — canonically the bare nickname at the end of the metadata row's second line, **exactly one badge per nickname** — never interactive. Two appearances: `default` (tonal primaryContainer) and `inverse` (near-black inverseSurface pair, reserved for the paid-expert **PRO** mark).
 
 **Reach for this when** the mark says *who the person is* — Channel owner (채널장), Verified (현직자), Moderator. **Skip when** the mark signals workflow state — pending / approved / rejected belong to [Status tag](../status-tag/status-tag.md) — or new-activity on a host — that's [Update](./update.md).

package/agents/components/badge/update.md

@@ -1,5 +1,7 @@
 # Update
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/badge/update.md`](../../../i18n/ko/schema/components/badge/update.md)
+
 A small brand-tone indicator attached to a host label — flagging *new or unread activity*. Two types share the brand fill and `radius.full` corner: **Numeric** (a labelled count pill) and **Dot** (a labelless update dot used by [Thumbnail](../thumbnail/thumbnail.md)). Always anchored to a host; never interactive.
 
 **Reach for Numeric when** the count itself carries meaning — 3 unread, 12 mentions, `99+` notifications. **Reach for Dot when** the presence of activity is the whole signal — a corner flag without a magnitude. **Skip Update** when the mark names *who the person is* rather than *what is new* — use [Role](./role.md) — or when it is descriptive metadata — use [Tag](../chip/tag.md).

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

@@ -1,6 +1,8 @@
 # Banner
 
-An in-body explanation block — a tinted card sitting within the reading flow with a short paragraph and an optional follow-through link. Two axes: **appearance** (`default` / `accent` / `destructive`), **leading slot** (`icon` / `thumbnail` / none).
+> 🇰🇷 한국어: [`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. 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)).
 
@@ -42,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.
@@ -77,6 +98,94 @@ import { Banner, Thumbnail } from '@teamblind-chorus/ui';
 </Banner>
 ```
 
+### 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.
+
+```preview
+banner/outlined
+---
+import { Banner } from '@teamblind-chorus/ui';
+
+// 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="default" outlined>
+    Stay active in the community to level up and unlock more of what the app offers.
+  </Banner>
+  <Banner appearance="accent" outlined>
+    Stay active in the community to level up and unlock more of what the app offers.
+  </Banner>
+</div>
+```
+
+### With 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.
+
+```preview
+banner/with-title
+---
+import { Banner } from '@teamblind-chorus/ui';
+
+<Banner
+  appearance="default"
+  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>
+```
+
+### With 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.
+
+```preview
+banner/with-trailing-icon
+---
+import { Banner } from '@teamblind-chorus/ui';
+import { ForwardCircleFillIcon } from '@teamblind-chorus/ui/icons';
+
+<Banner
+  appearance="default"
+  title="Level up faster"
+  trailingIcon={<ForwardCircleFillIcon size={16} />}
+>
+  Stay active in the community to level up and unlock more of what the app offers.
+</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.
@@ -100,31 +209,38 @@ import { StarIcon } from '@teamblind-chorus/ui/icons';
 
 Two appearances on the *emphasis* axis (plus `destructive` for errors). Banner carries no disabled state; only the optional action link follows the link state contract.
 
-| Appearance    | Container fill                                                                              | Body / action color                                                | 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` | Supplementary asides the reader can pass over without missing the main flow. |
-| `accent`      | `sys.color.primaryContainer`                                                                | body in `onPrimaryContainer`, action inherits                      | Asides worth pulling the eye toward — new-feature explainers, capability nudges. |
-| `destructive` | `sys.color.errorContainer`                                                                  | body in `onErrorContainer`, action inherits                        | Blocking errors or rejections — failed approvals, outages, billing.          |
+| 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.          |
 
 ## Slots
 
 - **container** — tinted block. Horizontal flex with `align-items: flex-start`; 12px inset, 8px sibling gap, 8px corner radius.
 - **icon** *(optional)* — 16 × 16 glyph. Slot height equals the `body.sm` line box so the glyph centres on the body's first line. Paints in `currentColor`.
 - **thumbnail** *(optional)* — leading [Thumbnail](../thumbnail/thumbnail.md). Takes precedence over `icon`; footprint and corner come from Thumbnail.
-- **content** — vertical column holding body and optional action; 8px stack gap; fills remaining inline space.
+- **content** — vertical column holding optional title, body, and optional action; 8px stack gap (4px title↔body); fills remaining inline space.
+- **title** *(optional)* — heading line above the body. `label.md` / Semibold / inherits container foreground. 4px (`sys.layout.stack.2xs`) gap to the body.
 - **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
 
 | Slot      | Token bindings |
 |-----------|----------------|
-| container | Fill + foreground per appearance, `sys.radius.md` (8), `sys.layout.container.sm` (12) padding, `sys.layout.stack.xs` (8) sibling gap, `align-items: flex-start` |
+| container | Fill + foreground per appearance, `sys.radius.md` (8), `sys.layout.container.sm` (12) padding, `sys.layout.stack.xs` (8) sibling gap, `align-items: flex-start`. With `outlined`: `sys.borderWidth.hairline` (1) inset stroke in the appearance's outline color |
 | icon      | `sys.icon.md` (16 × 16) glyph inside a slot whose height equals the body's first-line box (`calc(sys.typo.body.sm.size * sys.typo.body.sm.line)`); `color: currentColor` |
 | thumbnail | Delegated to [Thumbnail](../thumbnail/thumbnail.md); footprint-preserving (`flex: 0 0 auto`) |
-| content   | Flex column, `flex: 1 1 auto`, `sys.layout.stack.xs` (8) body↔action gap |
+| 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`. |
+| 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

@@ -15,11 +15,34 @@
       ],
       "default": "default"
     },
+    "outlined": {
+      "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."
+    },
+    "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,
+      "description": "Optional heading line above the body. label.md (14 / Semibold 600) in the container's foreground, separated from the body by `sys.layout.stack.2xs` (4). Reach for it when the aside needs a scannable lead-in; omit for single-thought asides where the body carries itself."
+    },
     "icon": {
       "type": "node",
       "optional": true,
       "description": "A 16 × 16 (`sys.icon.md`) glyph at the container's leading edge. Inherits the banner's foreground (`currentColor`) so the mark reads as part of the body copy. The slot occupies the body.sm line-box height so the glyph centers on the **first line** of the body — multi-line bodies keep the icon anchored to the first-line cap, not the block center. Ignored when `thumbnail` is also passed."
     },
+    "trailingIcon": {
+      "type": "node",
+      "optional": true,
+      "description": "A 16 × 16 (`sys.icon.md`) glyph at the container's trailing edge, vertically centered against the whole block (`align-self: center`). Paints in `currentColor`. Reach for it when the banner leads somewhere — a forward affordance such as `ForwardCircleFillIcon` signaling the whole aside opens a destination."
+    },
     "thumbnail": {
       "type": "node",
       "optional": true,
@@ -30,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,
@@ -58,9 +86,16 @@
     },
     "content": {
       "required": true,
-      "description": "Vertical column holding body and (optional) action. flex: 1 1 auto.",
+      "description": "Vertical column holding (optional) title, body, and (optional) action. flex: 1 1 auto.",
       "intrinsic": true
     },
+    "title": {
+      "required": false,
+      "description": "Optional heading line above the body. label.md (14 / Semibold) / inherits container's foreground. Separated from the body by `sys.layout.stack.2xs` (4) — tighter than the body↔action gap so title and body read as one passage.",
+      "accepts": [
+        "text"
+      ]
+    },
     "body": {
       "required": true,
       "description": "Explanation copy. body.sm / Regular / inherits container's foreground. Single paragraph; wraps freely.",
@@ -74,6 +109,20 @@
       "accepts": [
         "button"
       ]
+    },
+    "trailingIcon": {
+      "required": false,
+      "description": "16 × 16 (`sys.icon.md`) glyph slot at the trailing edge. Vertically centered against the container (`align-self: center`), paints in `currentColor`. Typically a forward affordance (e.g. `ForwardCircleFillIcon`).",
+      "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": {
@@ -84,8 +133,13 @@
     "iconSlotHeight": "calc(sys.typo.body.sm.size * sys.typo.body.sm.line)",
     "iconColor": "currentColor",
     "contentStackGap": "sys.layout.stack.xs",
+    "titleTypo": "sys.typo.label.md",
+    "titleGap": "sys.layout.stack.2xs",
     "bodyTypo": "sys.typo.body.sm",
-    "actionTypo": "sys.typo.label.md"
+    "actionTypo": "sys.typo.label.md",
+    "trailingIconSize": "sys.icon.md",
+    "trailingIconColor": "currentColor",
+    "outlineWidth": "sys.borderWidth.hairline"
   },
   "safeZone": {
     "inline": {
@@ -106,26 +160,33 @@
       "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."
     },
     "accent": {
       "background": "sys.color.primaryContainer",
       "foreground": "sys.color.onPrimaryContainer",
       "actionColor": "inherit",
-      "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."
+      "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. 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",
       "actionColor": "inherit",
+      "outlineColor": "color-mix(sys.color.error, 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."
     }
   },
   "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/bottom-sheet/bottom-sheet.md

@@ -1,5 +1,7 @@
 # Bottom sheet
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/bottom-sheet/bottom-sheet.md`](../../../i18n/ko/schema/components/bottom-sheet/bottom-sheet.md)
+
 An edge-anchored interruption — a panel that rises from the bottom of the viewport, sits over a scrim, and holds richer content than a Dialog can.
 
 **Reach for this when** you want to steer the user toward a preferred action *without severing the flow* — present enough to focus attention, light enough that dismissing returns them where they were. **Skip when** the decision must be committed before the flow can continue (use [Dialog](../dialog/dialog.md)).

package/agents/components/bubble/bubble.md

@@ -1,5 +1,7 @@
 # Bubble
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/bubble/bubble.md`](../../../i18n/ko/schema/components/bubble/bubble.md)
+
 A small persistent annotation pill with a tail pointing at an anchor — a chat-icon "new messages" flag, a search-bar campaign nudge, a feature-flag callout. Sibling of [Tooltip](../tooltip/tooltip.md): Tooltip is transient and overlays neighbours on hover; Bubble stays in view at the resting state, sits lower in visual priority (no elevation, smaller padding, single line), and never occludes the surrounding chrome.
 
 **Reach for this when** the annotation must remain readable as part of the resting UI. **Skip when** the hint is invoked on demand (use [Tooltip](../tooltip/tooltip.md)), carries a decision or blocking meaning (use [Banner](../banner/banner.md) / [Dialog](../dialog/dialog.md)), or is just a numeric count beside an icon (use [Badge](../badge/badge.md)).

package/agents/components/button/button.family.json

@@ -19,10 +19,11 @@
   "visualReuse": "open",
   "layoutInset": "inline",
   "usage": {
-    "note": "All button roles are the single `Button` export selected by the `variant` prop — there is NO `<Fab>`, `<IconButton>`, `<ToggleButton>`, or `<Toolbar>` export. An `import { Fab }` failure does NOT mean the family is missing; reach for `<Button variant=\"fab\">`.",
+    "note": "All button ROLES are the single `Button` export selected by the `variant` prop — there is NO `<Fab>`, `<IconButton>`, `<ToggleButton>`, or `<Toolbar>` export. An `import { Fab }` failure does NOT mean the family is missing; reach for `<Button variant=\"fab\">`. The one separate named export is `ButtonGroup` (the `group` sub) — a layout wrapper for two or more Buttons, NOT a Button variant.",
     "subs": {
       "fab": { "variant": "fab", "example": "<Button variant=\"fab\" appearance=\"primary\" icon={<EditIcon />}>글쓰기</Button>" },
-      "icon": { "variant": "icon", "example": "<Button variant=\"icon\" aria-label=\"…\" icon={<MoreIcon />} />" }
+      "icon": { "variant": "icon", "example": "<Button variant=\"icon\" aria-label=\"…\" icon={<MoreIcon />} />" },
+      "group": { "import": "ButtonGroup", "example": "<ButtonGroup variant=\"docked\" label={<>선택한 직군: <strong>SW개발</strong></>}><Button appearance=\"outlined\" size=\"large\">연봉 정보</Button><Button appearance=\"primary\" size=\"large\">추천 채용공고</Button></ButtonGroup>", "note": "Named export — NOT a Button variant (there is no `<Button variant=\"group\">`). Lays out adjacent Buttons; `variant=\"docked\"` is the bottom-pinned action bar (surface + 16px inset + 8px gap + upward `sys.elevation.sheet` shadow + optional `label`). Renders in flow — PageShell owns the pinning." }
     }
   },
   "spec": "button.md",
@@ -33,6 +34,11 @@
       "md": "button.md",
       "default": true
     },
+    {
+      "slug": "group",
+      "spec": "group.spec.json",
+      "md": "standard.md"
+    },
     {
       "slug": "fab",
       "spec": "fab.spec.json",

package/agents/components/button/button.md

@@ -1,5 +1,7 @@
 # Button
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/button/button.md`](../../../i18n/ko/schema/components/button/button.md)
+
 The action-surface family. **Standard Button** is the default inline filled / outlined / tertiary control; the rest specialise by **shape · context · footprint**: floating canvas commit (FAB), glyph-only capsule (Icon Button), chromeless link-shaped commit (Text Button), dense capsule for toolbars and tabs (Toolbar Button), reversible commit at the Toolbar footprint (Toggle Button), option-toggle with leading checkbox (Check Button). Per-sub intent lives on each sub's page.
 
 **Layout inset.** `inline` — slot atom. No page-rail responsibility; the surrounding container places it. Lives inside another component's slot (List row trailing, Section header trailing, NavigationBar trailing, BottomSheet action stack) or inside a layout `<div>` that already pays the page gutter. The FAB sub is the one exception — pinned to the page viewport, not the row rail.

package/agents/components/button/check.md

@@ -1,5 +1,7 @@
 # Check
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/button/check.md`](../../../i18n/ko/schema/components/button/check.md)
+
 Option-toggle commit — a [Text Button](./text.md) with a required leading checkbox glyph that flips outline → fill on `checked`, plus an optional middle icon. Two sizes (`medium` / `small`) where the checkbox footprint is the differentiator.
 
 **Reach for this when** an option is committed alongside the surface's main action — *Use this perk?*, *Apply offer*, *Keep me signed in*. **Skip when** the row is a form-bound checkbox input (out-of-system), the commit is a one-shot action ([Text Button](./text.md)), or the row needs a radio's single-select contract ([Radio list](../list/radio.md)).

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.md

@@ -1,5 +1,7 @@
 # FAB
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/button/fab.md`](../../../i18n/ko/schema/components/button/fab.md)
+
 Floating action button — surface-elevated commit anchored to the canvas, reachable while content scrolls. Single fixed rung with a pill geometry (`sys.radius.full`) and floating elevation (`sys.elevation.floating`); label and icon both optional, at least one present.
 
 **Reach for this when** the canvas needs a single headline action that survives scroll — Compose, Add, Create. **Skip when** the action lives inline with content (use [Standard Button](./standard.md)) or the row is a dense toolbar ([Toolbar Button](./toolbar.md)).