@teamblind-chorus/ui 1.0.1 → 1.2.0

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

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

package/agents/components/button/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/icon.spec.json

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

package/agents/components/button/standard.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/standard.spec.json

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

package/agents/components/button/text.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/text.spec.json

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

package/agents/components/button/toggle.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/toggle.spec.json

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

package/agents/components/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.

package/agents/components/carousel/post.md

@@ -1,5 +1,7 @@
 # Post
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/carousel/post.md`](../../../i18n/ko/schema/components/carousel/post.md)
+
 Sub-component of the [Carousel](./carousel.md) family. Horizontally-scrolling pager of up to 5 compact post cards — surfaces curated popular posts or gives paid / verified accounts priority placement inside the [Post](../feed/post.md) feed column. The section heading and `See all` link live on the [Carousel](./carousel.md) wrapper — PostCarousel is the *content* only.
 
 **Reach for this when** spotlighting a small set (≤5) of curated or sponsored posts inside a feed column. **Skip when** the surface is a single feed stream ([Feed · Post](../feed/post.md)) or an entity directory ([List/entry](../list/entry.md)).
@@ -108,7 +110,7 @@ import { Carousel, PostCarousel } from '@teamblind-chorus/ui';
   - **body** — `sys.typo.body.sm` / `sys.color.onSurfaceVariant`. Three-line clamp.
   - **mention** *(optional)* — `sys.typo.body.sm` / `sys.color.primary` (not italic).
   - **footer** — leading 'See more' [Text Button](../button/text.md) (`xsmall` / `secondary`) + trailing view count (`EyeIcon` + count `<span>`).
-- **pagination** — one dot per card; active `sys.color.onSurface`, rest `sys.color.outlineVariant`. Decorative (`aria-hidden`).
+- **pagination** — [Pagination](../pagination/pagination.md) component, one dot per card (`count` = card count, `activeIndex` from scroll position). Decorative — dot tokens and the `aria-hidden` contract live on its spec; the carousel centers the intrinsic-width row (`align-self: center`).
 
 ## Anatomy
 
@@ -123,7 +125,7 @@ import { Carousel, PostCarousel } from '@teamblind-chorus/ui';
 | body / mention    | `sys.typo.body.sm` / `sys.color.onSurfaceVariant` (three-line clamp) · mention in `sys.color.primary` |
 | followAction      | [Text Button](../button/text.md) `size={'xsmall'}`, `appearance={'accent'}` inactive → `appearance={'default'}` active; state tokens delegate to Text Button |
 | footer            | Row: leading 'See more' Text Button (`xsmall` / `secondary`) + trailing view count `<span>`; `justify-content: space-between` |
-| pagination dot    | 6 × 6, `sys.radius.full`; active `sys.color.onSurface`, inactive `sys.color.outlineVariant`; `sys.layout.inline.sm` row gap |
+| pagination dot    | [Pagination](../pagination/pagination.md) component delegated verbatim — 6 × 6 dots, active/inactive colors, and row gap bind on its spec |
 
 ## Sizes
 
@@ -144,5 +146,5 @@ Inward — cards tile inside a horizontal scroll viewport with hairline outlines
 - **Card header renders the shared `EntryRow`.** The avatar + optional verified mark + channel label + trailing follow [Text Button](../button/text.md) row pinned to the top of each *card* is **the same `EntryRow` atom that [List/entry](../list/entry.md) rows render** — not a look-alike, the literal shared component. The carousel passes `verified` (the inline `VerifiedFillIcon`, left of the label), a 40-rung `thumbnail`, and a `xsmall` follow Text Button (`accent` inactive → `default` active) into `EntryRow`'s trailing slot; the leading→label gap (12), identity column, and trailing-action pin all live on `EntryRow`. Only the surrounding card chrome (`chorus-post-carousel__card-header` wrapper) is carousel-specific. Retune the attribution shape on `EntryRow` / at [List/entry](../list/entry.md), not here.
 - **One card per page, scroll-snap.** `scroll-snap-type: x mandatory`; each card declares `scroll-snap-align: start`. The pager re-pays the 16 left rail via `padding-left` and, as a full-bleed child, reaches the trailing edge intrinsically so the peek isn't clipped.
 - **Guaranteed 40px peek.** Trailing-edge visibility of the next card pins to `ref.space.500` — raw ref step so the floor is fixed-pixel across breakpoints. Card basis is `calc(100% - sys.layout.inline.md - ref.space.500)`. After every swipe, the snapped card aligns flush with the container's left padding; the trailing edge always holds the 40px peek.
-- **Pagination dots are decorative.** Dots reflect scroll position via `IntersectionObserver`; tapping a dot does not scroll. Active dot paints `sys.color.onSurface`, the rest `sys.color.outlineVariant`.
+- **Pagination dots are decorative.** The dot row is the shared [Pagination](../pagination/pagination.md) component. The carousel derives the active index via `IntersectionObserver` on the pager's snap targets and passes it down; tapping a dot does not scroll.
 - **Cards route via `onClick`.** When an item carries `onClick`, the card surface becomes the click target; header (follow action) and footer (more link) intercept the tap so each routes independently.

package/agents/components/carousel/post.spec.json

@@ -94,7 +94,7 @@
     },
     "pagination": {
       "required": true,
-      "description": "Row of dots below the pager — one per card. Active dot paints `sys.color.onSurface`, the rest paint `sys.color.outlineVariant`. Decorative (`aria-hidden`); the active index updates from the pager's scroll position via IntersectionObserver.",
+      "description": "Row of dots below the pager — rendered by the [Pagination](../pagination/pagination.md) component (`count` = card count, `activeIndex` from the pager's scroll position via IntersectionObserver). Dot size / gap / colors and the `aria-hidden` decorative contract all come from the Pagination spec; Pagination renders nothing below two cards. Pagination is an intrinsic-width inline element — the carousel centers it (`align-self: center` on the carousel's own selector).",
       "intrinsic": true
     }
   },
@@ -134,10 +134,8 @@
     "cardFooterColor": "sys.color.onSurfaceVariant",
     "cardFooterIcon": "EyeIcon",
     "cardFooterIconSize": "sys.icon.md",
-    "paginationDotSize": "ref.space.75",
-    "paginationDotGap": "sys.layout.inline.sm",
-    "paginationActiveColor": "sys.color.onSurface",
-    "paginationInactiveColor": "sys.color.outlineVariant"
+    "paginationRendersAs": "Pagination component — dot size / gap / radius and active / inactive colors all delegate to the [Pagination](../pagination/pagination.md) spec.",
+    "paginationAlign": "center — Pagination is an intrinsic-width inline element; the carousel binds `align-self: center` on its own selector to center the row under the pager."
   },
   "itemProps": {
     "id": {
@@ -210,7 +208,7 @@
     "horizontalScrollSnap": "scroll-snap-type: x mandatory; each card declares scroll-snap-align: start.",
     "nextCardPeek": "The Carousel host is full-bleed, so the pager spans the full surface width and reaches the trailing edge intrinsically (no negative margin); it re-pays the 16 left rail via `padding-left: sys.layout.container.md`. Card basis composes the inter-card gap (`sys.layout.inline.md`) plus the visible peek (`ref.space.500`, 40px) into one calc — a minimum of 40px of the next card is guaranteed to remain visible at the trailing edge whenever a card is snapped to the leading edge. The peek is pinned to a raw ref step rather than a responsive sys-layout rung so the visibility floor is fixed-pixel and does not shift at the responsive breakpoint.",
     "stickyToLeadingPadding": "After every swipe, the snapped card aligns flush with the pager's left padding (the 16 rail) — it 'sticks' to the leading edge of the pager. `scroll-snap-align: start` plus the pager's `scroll-padding-left: sys.layout.container.md` together produce this behavior. The trailing edge of the same snap state always holds the 40px peek of the next card; the two are one geometry contract, not two independent rules.",
-    "paginationDecorative": "Dots are decorative (`aria-hidden`). They reflect the scroll position only; tapping a dot does not scroll. Active state updates via IntersectionObserver on the pager's snap targets.",
+    "paginationDecorative": "Dots render via the [Pagination](../pagination/pagination.md) component and are decorative (`aria-hidden`). They reflect the scroll position only; tapping a dot does not scroll. The carousel derives the active index via IntersectionObserver on the pager's snap targets and passes it down as `activeIndex`.",
     "cardClickRoutes": "When an item carries `onClick`, the card surface becomes the click target. Header affordances (follow action) and footer affordances (more link) intercept the tap so each can route independently.",
     "insertionPolicy": "Editorial / ops control inserts the carousel between regular Feed cards according to placement policy — the component does not own that decision."
   },

package/agents/components/carousel/profile.md

@@ -1,5 +1,7 @@
 # Profile
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/carousel/profile.md`](../../../i18n/ko/schema/components/carousel/profile.md)
+
 Sub-component of the [Carousel](./carousel.md) family. Horizontally-scrolling rail of fixed-width (176px) profile cards — channels, user profiles, or company channels grouped under a single editorial heading. Each card carries a cover band, an overlapping 64-rung avatar, entity name + follower count, a metrics row or two-line description, and a trailing follow [Toggle Button](../button/text.md).
 
 **Reach for this when** an editorial collection groups follow-able entities under a single heading — hot companies, recommended channels, suggested people. **Skip when** the rail carries content posts ([Post carousel](./post.md)), the surface needs the full list scanned vertically ([SuggestionList](../suggestion-list/suggestion-list.md) / [DirectoryList](../directory-list/directory-list.md)), or the rung is a label-only nav strip ([AvatarRail](../avatar-rail/avatar-rail.md)).
@@ -152,7 +154,7 @@ import { Carousel, ProfileCarousel } from '@teamblind-chorus/ui';
   - **metrics** *(optional)* — row of `icon + value` chips: `star → StarFillIcon (sys.color.icon.yellow)`, `pulse → PulseFillIcon (sys.color.success)`, `heart → HeartFillIcon (sys.color.icon.red)`. Mutually exclusive with `description`.
   - **description** *(optional)* — two-line clamped paragraph that replaces the metrics row when present. Block height fixed to two lines of `sys.typo.label.sm` regardless of copy length, so card height stays consistent across metrics-carrying and copy-carrying cards.
   - **followAction** — full-width [Toggle Button](../button/text.md) (`variant={'toggle'}`); `Follow` (inactive) / `Following` (active).
-- **pagination** — one dot per card. Active dot paints `sys.color.onSurface`; rest paint `sys.color.outlineVariant`. Decorative.
+- **pagination** — [Pagination](../pagination/pagination.md) component, one dot per card (`count` = card count, `activeIndex` from scroll position). Decorative — dot tokens and the `aria-hidden` contract live on its spec; the carousel centers the intrinsic-width row (`align-self: center`).
 
 ## Anatomy
 
@@ -168,7 +170,7 @@ import { Carousel, ProfileCarousel } from '@teamblind-chorus/ui';
 | metric chip    | `sys.icon.md` glyph + `sys.typo.label.sm` value; star → `StarFillIcon` (`sys.color.icon.yellow`), pulse → `PulseFillIcon` (`sys.color.success`), heart → `HeartFillIcon` (`sys.color.icon.red`) |
 | description    | `sys.typo.label.sm` / `sys.color.onSurfaceVariant`, centered, two-line clamp with trailing ellipsis. Two-layer DOM — outer container owns the same fixed-height slot as `metrics row` (min/max-height = 2 label.sm lines); inner `<p>` owns the `-webkit-line-clamp: 2` truncation. Split sidesteps a Chrome quirk where `display: -webkit-box` and explicit `height` on one element break the third-line clip. |
 | followAction   | [Toggle Button](../button/text.md) (Chip-toggle anatomy), stretched to full card width |
-| pagination dot | 6×6, `sys.radius.full`; active `sys.color.onSurface`, inactive `sys.color.outlineVariant` |
+| pagination dot | [Pagination](../pagination/pagination.md) component delegated verbatim — 6 × 6 dots, active/inactive colors, and row gap bind on its spec |
 
 ## States
 

package/agents/components/carousel/profile.spec.json

@@ -80,7 +80,7 @@
     },
     "pagination": {
       "required": true,
-      "description": "Row of dots below the pager — one per card. Active dot paints `sys.color.onSurface`; the rest paint `sys.color.outlineVariant`. Decorative (`aria-hidden`); the active index updates from the pager's scroll position via IntersectionObserver.",
+      "description": "Row of dots below the pager — rendered by the [Pagination](../pagination/pagination.md) component (`count` = card count, `activeIndex` from the pager's scroll position via IntersectionObserver). Dot size / gap / colors and the `aria-hidden` decorative contract all come from the Pagination spec; Pagination renders nothing below two cards. Pagination is an intrinsic-width inline element — the carousel centers it (`align-self: center` on the carousel's own selector).",
       "intrinsic": true
     }
   },
@@ -123,10 +123,8 @@
     "followActionRendersAs": "Button variant='toggle' — Chip-toggle anatomy. Stretched to full card width via a wrapper rule. All state tokens delegate to the Toggle Button (Chip) family.",
     "cardPaddingBlock": "sys.layout.stack.sm",
     "cardPaddingInline": "sys.layout.container.md",
-    "paginationDotSize": "ref.space.75",
-    "paginationDotGap": "sys.layout.inline.sm",
-    "paginationActiveColor": "sys.color.onSurface",
-    "paginationInactiveColor": "sys.color.outlineVariant"
+    "paginationRendersAs": "Pagination component — dot size / gap / radius and active / inactive colors all delegate to the [Pagination](../pagination/pagination.md) spec.",
+    "paginationAlign": "center — Pagination is an intrinsic-width inline element; the carousel binds `align-self: center` on its own selector to center the row under the pager."
   },
   "itemProps": {
     "id": {
@@ -198,7 +196,7 @@
     "fixedCardWidth": "Every profile card paints a fixed 176px footprint — the carousel never reflows the card to fit the available inline width. The trailing peek (`ref.space.500`, 40px) of the next card is always visible regardless of viewport.",
     "horizontalScrollSnap": "scroll-snap-type: x mandatory; each card declares scroll-snap-align: start.",
     "stickyToLeadingPadding": "After every swipe, the snapped card aligns flush with the pager's left padding (the 16 rail) — same geometry contract as PostCarousel.",
-    "paginationDecorative": "Dots are decorative; tapping a dot does not scroll. Active state updates via IntersectionObserver on the snap targets.",
+    "paginationDecorative": "Dots render via the [Pagination](../pagination/pagination.md) component and are decorative; tapping a dot does not scroll. The carousel derives the active index via IntersectionObserver on the snap targets and passes it down as `activeIndex`.",
     "followToggleCommitsInPlace": "Tapping Follow flips the card's Toggle Button to Following and stays there. State is owned by the consumer via items[i].followed + onFollowChange.",
     "cardClickRoutes": "When an item carries `onClick`, the card surface becomes the click target. The follow toggle intercepts the tap so it routes independently."
   },

package/agents/components/chip/chip.md

@@ -1,5 +1,7 @@
 # Chip
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/chip/chip.md`](../../../i18n/ko/schema/components/chip/chip.md)
+
 A small, content-shaped control or label — chip-shaped affordance for two anchoring roles. **Filter** is the selectable, capsule-shaped choice the user toggles to refine a set (search filters, taxonomy switches, faceted lists). **Tag** is the static, square-cornered label naming attached metadata (categories on a card, attributes on a profile, opt-in/out tokens on a settings row). Each family carries its own slot vocabulary, geometry, and tone; the cross-family contract is limited to the shared label rung (12px Semibold, 4px block padding, 4px label-slot inset producing the visible icon-to-label rhythm) and the Chorus-wide color / state / focus tokens in [`DESIGN.md`](../../DESIGN.md). The two diverge on min-height and horizontal padding by role — **Filter** sits at 32 / 12 (tappable affordance, shared verbatim with [Toolbar Button](../button/toolbar.md) and [Tabs Segmented](../tabs/segmented.md)); **Tag** tightens to 24 / 8 (passive metadata that should not invite touch).
 
 **Layout inset.** `inline` — slot atom. A single Chip has no page-rail responsibility; the surrounding container places it (List row leading, Feed footer, FormField suffix). A Chip *group* — multiple Filter chips arranged as a filter rail — is rail-responsible: place the group as a direct child of the page shell (no `padding-inline` / `px-*` wrapper) and let its outer container pay the gutter once, so the first chip's leading edge aligns with section H2s and list-row leading content. See [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).

package/agents/components/chip/filter.md

@@ -1,5 +1,7 @@
 # Filter
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/chip/filter.md`](../../../i18n/ko/schema/components/chip/filter.md)
+
 The selectable chip — a capsule-shaped toggle for refining a set. Unselected is a transparent hairline-outlined pill that adopts whatever surface sits behind it; selected swaps to an inverse fill. Optional leading/trailing icons compose without changing footprint.
 
 **Reach for this when** the user narrows a set by toggling one or more independent criteria — multiple chips can be on at once. **Skip when** the choices are mutually-exclusive view modes — use [Segmented](../tabs/segmented.md) instead.

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

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

package/agents/components/chip/tag.md

@@ -1,5 +1,7 @@
 # Tag
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/chip/tag.md`](../../../i18n/ko/schema/components/chip/tag.md)
+
 The informational chip — square-cornered label naming attached metadata (categories, statuses, content labels). Shorter than Filter (24 vs 32 min-height) with `sys.radius.sm` corners. Two appearances: `default` paints a translucent `sys.color.scrimSubtle` overlay (~8% inverse-tone, adopts whatever surface sits behind it); `accent` paints a tonal pale-primary container with primary label.
 
 **Reach for this when** you're naming attached metadata on rows, cards, or profiles. **Skip when** the marker signals unread / new activity on a host rather than describing it — use [Badge](../badge/badge.md) instead.

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

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

package/agents/components/dialog/dialog.md

@@ -1,5 +1,7 @@
 # Dialog
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/dialog/dialog.md`](../../../i18n/ko/schema/components/dialog/dialog.md)
+
 A focused, opt-in interruption — a centred card over a scrim that holds the flow until the user makes a single decision.
 
 **Reach for this when** the flow must pause for a definitive response — destructive actions, conflicts, consent gates, "Are you sure?". **Skip when** the same nudge can be delivered without halting the flow (use [Bottom sheet](../bottom-sheet/bottom-sheet.md)), the message is contextual to underlying content ([Banner](../banner/banner.md)), or the confirmation is post-action ([Toast](../toast/toast.md)).

package/agents/components/directory-list/directory-list.md

@@ -1,5 +1,7 @@
 # Directory list
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/directory-list/directory-list.md`](../../../i18n/ko/schema/components/directory-list/directory-list.md)
+
 A vertical follow-list — labelled block where each row pairs a 48 [Thumbnail](../thumbnail/thumbnail.md), an identity column (name + `secondary` followers + `description`), and a trailing [Toggle Button](../button/toggle.md) flipping between "Follow" and "Following". Anatomy is entity-agnostic — channels, people, companies, topics share one shape.
 
 **Preset wrapper.** Internally this is `<Header /> + <List variant="entry" size="large" divider={false}>`. The wrapper exists to (a) map entity-flavored item keys (`name → label`, `followers → secondary`, `active/onToggle → trailingIcon`) and (b) lock the rung + divider preset for the canonical Follow-able directory shape. There is no new visual grammar — just a pinned set of `List` props plus item-key sugar.

package/agents/components/divider/divider.md

@@ -1,5 +1,7 @@
 # Divider
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/divider/divider.md`](../../../i18n/ko/schema/components/divider/divider.md)
+
 A section-break band — a single full-bleed block painted with `sys.color.scrimSubtle` (~8% inverse-tone overlay — black in light mode, white in dark) at a fixed block thickness of `sys.layout.stack.xs` (8). Reach for it when two adjacent regions don't share an enclosing container and vertical rhythm alone doesn't read as a boundary — a directory of suggested channels ending and a fresh recommendation list beginning, a feed segment ending and a followed-channels list resuming, a promo strip ending and content picking up below.
 
 **Reach for this when** the boundary between two regions is ambiguous because they share the same surface and vertical rhythm — the visitor's eye should *land* on the break, not infer it. **Skip when** the regions already sit on different surfaces (one card, one canvas — the surface change is the break), when one region carries a heading that itself reads as the start of a new block, or when the separation is between *rows of the same list* (List's own `divider={true}` paints those as a hairline `outlineVariant` rule).

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

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