@teamblind-chorus/ui 1.0.0 → 1.1.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, 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.
 - **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
 
@@ -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
 

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/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.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. Four axes: **appearance** (`default` / `accent` / `destructive`), **outline** (`outlined` / none), **leading slot** (`icon` / `thumbnail` / none), **trailing slot** (`trailingIcon` / 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)).
 
@@ -77,6 +79,63 @@ 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 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 +159,35 @@ 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. |
+| `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`.
 
 ## 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` |
 
 ## States
 

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

@@ -15,11 +15,27 @@
       ],
       "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."
+    },
+    "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,
@@ -58,9 +74,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 +97,13 @@
       "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"
+      ]
     }
   },
   "sizing": {
@@ -84,8 +114,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,18 +141,21 @@
       "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",
+      "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."
     },
     "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."
     }
   },

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/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)).

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

@@ -0,0 +1,65 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "ButtonGroup",
+  "family": "button",
+  "subcomponent": "group",
+  "description": "Lays out two or more Buttons as one composition so consumers never hand-roll the wrapper div. A NAMED export (`import { ButtonGroup }`) — NOT a Button variant. Three forms share the family's 8px (`sys.layout.inline.md`) gap: inline horizontal (default), inline vertical (`orientation=\"vertical\"`), and docked (`variant=\"docked\"`) — a footer bar pinned to the bottom of the app. The docked form adds full-bleed `sys.color.surface`, a 16px (`sys.layout.container.md`) inset, an upward `sys.elevation.sheet` shadow (no top stroke), and an optional `label` above the row.",
+  "element": "div",
+  "props": {
+    "variant": {
+      "type": "enum",
+      "values": [
+        "inline",
+        "docked"
+      ],
+      "default": "inline"
+    },
+    "orientation": {
+      "type": "enum",
+      "values": [
+        "horizontal",
+        "vertical"
+      ],
+      "default": "horizontal",
+      "note": "Applies to the `inline` variant. `docked` is always a single horizontal row."
+    },
+    "label": {
+      "type": "node",
+      "optional": true,
+      "note": "Optional caption above the row. Rendered in `sys.typo.body.md` (16px) / `sys.color.onSurfaceVariant`, centered. An inline <strong> reads as the emphasized value in the full-strength on-surface tone."
+    }
+  },
+  "slots": {
+    "children": {
+      "required": true,
+      "description": "The Buttons to group. In the `docked` variant they split the row equally (each `flex: 1`), so no per-Button `fullWidth` is needed.",
+      "accepts": [
+        "button"
+      ]
+    },
+    "label": {
+      "required": false,
+      "description": "Optional caption above the row (`label` prop). `sys.typo.body.md` (16px), `sys.color.onSurfaceVariant`, centered, 16px (`sys.layout.stack.md`) above the row.",
+      "accepts": [
+        "text"
+      ]
+    }
+  },
+  "anatomy": {
+    "gap": "sys.layout.inline.md (8) — between Buttons, both axes",
+    "labelStackGap": "sys.layout.stack.md (16) — label → row",
+    "docked": {
+      "background": "sys.color.surface",
+      "padding": "sys.layout.container.md (16) — all four sides",
+      "elevation": "sys.elevation.sheet — upward shadow, the same one Bottom Sheet / Side Sheet cast",
+      "border": null,
+      "split": "each Button flex: 1 1 0 — they share the row equally"
+    }
+  },
+  "forbidden": [
+    "raw wrapper <div> with hand-rolled flex/gap instead of <ButtonGroup> — the gap, surface, and shadow are the component's contract",
+    "`variant=\"docked\"` self-pinned with position: sticky/fixed — like the other bars it renders in flow; PageShell owns the pinning",
+    "top `border` / hairline on the docked bar — separation from the scrolling body is the upward `sys.elevation.sheet` shadow, not a stroke",
+    "reaching for ButtonGroup as `<Button variant=\"group\">` — it is its own named export, not a Button variant"
+  ]
+}

package/agents/components/button/icon.md

@@ -1,5 +1,7 @@
 # Icon
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/button/icon.md`](../../../i18n/ko/schema/components/button/icon.md)
+
 The icon-only commit surface — circular transparent target carrying a single glyph. Two rungs: `large` (40 × 40 / 24-glyph) for page chrome, `medium` (32 × 32 / 16-glyph) for inside-control density.
 
 **Reach for this when** the control's identity is the glyph and the action is reversible — [Navigation bar](../navigation-bar/navigation-bar.md) search/chat, [Dialog](../dialog/dialog.md) dismiss, feed-row "⋯". **Skip when** the action is destructive or one-shot — use standard [Button](./button.md) with a visible verb.

package/agents/components/button/standard.md

@@ -1,5 +1,7 @@
 # Standard
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/button/standard.md`](../../../i18n/ko/schema/components/button/standard.md)
+
 The default inline action surface — a labelled commit (form submit, dialog confirm, row action). Two axes: **size** (`large` / `medium` / `small`), **appearance** (`primary` / `secondary` / `outlined` / `tertiary`).
 
 **Reach for this when** you need a labelled commit inline with content — Save, Continue, Confirm, Cancel. **Skip when** the commit must float above scrolling content ([FAB](./fab.md)), the rung is body-text-sized ([Text Button](./text.md)), or the row is a dense toolbar ([Toolbar Button](./toolbar.md)).
@@ -103,36 +105,60 @@ import { Button } from '@teamblind-chorus/ui';
 
 ### Group
 
-Adjacent Buttons share an **8px** gap (`sys.layout.inline.md` horizontal / `sys.layout.stack.xs` vertical). Horizontal: outlined left, primary right. Vertical: primary top, secondary below.
+Compose adjacent Buttons with **`ButtonGroup`** instead of a hand-rolled wrapper — it owns the family's **8px** gap (`sys.layout.inline.md`). Horizontal (default): outlined left, primary right. Vertical (`orientation="vertical"`): primary top, secondary below.
 
 ```preview
 button/standard/group
 ---
-import { Button } from '@teamblind-chorus/ui';
+import { Button, ButtonGroup } from '@teamblind-chorus/ui';
 
-<div style={{ display: 'flex', gap: 8 }}>
-  <Button appearance="outlined" size="large">
-    See more
-  </Button>
-  <Button appearance="primary" size="large">
-    Confirm
-  </Button>
-</div>
+<ButtonGroup aria-label="Group example">
+  <Button appearance="outlined" size="large">See more</Button>
+  <Button appearance="primary" size="large">Confirm</Button>
+</ButtonGroup>
 ```
 
 ```preview
 button/standard/group-vertical
 ---
-import { Button } from '@teamblind-chorus/ui';
+import { Button, ButtonGroup } from '@teamblind-chorus/ui';
+
+<ButtonGroup orientation="vertical" aria-label="Group example">
+  <Button appearance="primary" size="large" fullWidth>Save</Button>
+  <Button appearance="secondary" size="large" fullWidth>Cancel</Button>
+</ButtonGroup>
+```
 
-<div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
-  <Button appearance="primary" size="large">
-    Save
-  </Button>
-  <Button appearance="secondary" size="large">
-    Cancel
-  </Button>
-</div>
+### Docked action bar
+
+`ButtonGroup` with **`variant="docked"`** — two **Large** Buttons combined into a footer bar pinned to the bottom of the app, the screen-level commit row for a flow (a picker, a form, a detail view). Full-bleed `sys.color.surface` with a **16px** inset (`sys.layout.container.md`); the two Buttons split the row equally at the family's 8px gap (`sys.layout.inline.md`). No top stroke — instead an upward `sys.elevation.sheet` shadow (the same one [Bottom Sheet](../bottom-sheet/bottom-sheet.md) / [Side Sheet](../side-sheet/side-sheet.md) cast) lifts it off the scrolling body, so content passing behind reads as a separate region. Supplementary **outlined** left, **primary** commit right. Renders in flow — like the other bars it must **not** self-pin (`position: sticky`/`fixed`); [Page Shell](../page-shell/page-shell.md) owns the pinning.
+
+```preview
+button/standard/docked-bar
+---
+import { Button, ButtonGroup } from '@teamblind-chorus/ui';
+
+<ButtonGroup variant="docked" aria-label="Page actions">
+  <Button appearance="outlined" size="large">Salary info</Button>
+  <Button appearance="primary" size="large">View jobs</Button>
+</ButtonGroup>
+```
+
+An **optional text label** sits above the row — pass it via the `label` prop. It's a caption echoing what the Buttons act on (the current selection, a running total), rendered in `sys.typo.body.md` (**16px**) / `sys.color.onSurfaceVariant`, centered, separated from the row by `sys.layout.stack.md` (16px); an inline `<strong>` reads as the emphasized value in the full-strength on-surface tone.
+
+```preview
+button/standard/docked-bar-labeled
+---
+import { Button, ButtonGroup } from '@teamblind-chorus/ui';
+
+<ButtonGroup
+  variant="docked"
+  aria-label="Page actions"
+  label={<>Selected role: <strong>SW Engineer</strong></>}
+>
+  <Button appearance="outlined" size="large">Salary info</Button>
+  <Button appearance="primary" size="large">View jobs</Button>
+</ButtonGroup>
 ```
 
 ### Truncation

package/agents/components/button/text.md

@@ -1,5 +1,7 @@
 # Text
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/button/text.md`](../../../i18n/ko/schema/components/button/text.md)
+
 The link-shaped commit surface — reads as text at rest, paints a button-like hover overlay and focus ring on interaction. Two axes: **appearance** (`default` / `accent` / `onPrimary` / `inverse`), **size** (`medium` / `small` / `xsmall`).
 
 **Reach for this when** the action is inline next to typographic content and commits — *Skip*, *Edit*, *Resend*, a section's trailing *See all*. **Skip when** the affordance navigates — use [Text link](../../DESIGN.md#text-links).

package/agents/components/button/toggle.md

@@ -1,5 +1,7 @@
 # Toggle
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/button/toggle.md`](../../../i18n/ko/schema/components/button/toggle.md)
+
 Commit-and-record action — a Toolbar-footprint button with two states. **Inactive** invites the commit (`primary` fill); **active** records it (`transparent` fill + hairline `outlineVariant` outline).
 
 **Reach for this when** you need a reversible commit that persists across views — *Follow / Following*, *Subscribe / Subscribed*, *Join / Joined*. **Skip when** the action is one-shot ([Standard Button](./standard.md)), the row is a dense toolbar ([Toolbar Button](./toolbar.md)), or the toggle belongs to a filter set ([Filter Chip](../chip/filter.md)).

package/agents/components/button/toolbar.md

@@ -1,5 +1,7 @@
 # Toolbar
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/button/toolbar.md`](../../../i18n/ko/schema/components/button/toolbar.md)
+
 Dense inline action — a 32-tall capsule for toolbars, table-row actions, and inline menu triggers. Chrome shared with [Filter chip](../chip/filter.md) and [Tabs Segmented](../tabs/segmented.md) so mixed rows read at one density; divergence is intent (Toolbar fires, Filter toggles, Segmented enforces single-select).
 
 **Reach for this when** a dense row needs an inline action — toolbar opener, table-row action, inline menu trigger. **Skip when** the standard inline shape fits ([Button](./button.md)), the affordance floats above content ([FAB](./fab.md)), or the row is body-text density ([Text Button](./text.md)).

package/agents/components/carousel/carousel.md

@@ -1,5 +1,7 @@
 # Carousel
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/carousel/carousel.md`](../../../i18n/ko/schema/components/carousel/carousel.md)
+
 Page-region wrapper for editorial collections — a labelled block with a leading heading and an optional trailing `See all` link, hosting a horizontal swipeable rail underneath. Carousel owns the chrome (surface, padding, header anatomy); each sub owns only its pager + cards.
 
 - **[Post](./post.md)** — a swipeable rail of compact post cards. Surfaces a curated set of popular posts or gives paid / verified accounts priority placement inside the feed column.