@teamblind-chorus/ui 1.0.1 → 1.2.0

package/agents/components/pagination/pagination.md

@@ -0,0 +1,40 @@
+# Pagination
+
+> 🇰🇷 한국어: [`i18n/ko/schema/components/pagination/pagination.md`](../../../i18n/ko/schema/components/pagination/pagination.md)
+
+Decorative dot-position indicator for one-page-at-a-time pagers — an inline row of 6px dots, one per page, the active dot painted `sys.color.onSurface` and the rest `sys.color.outlineVariant`.
+
+**Reach for this when** a horizontally-snapping pager needs to show where the user is — carousel cards ([PostCarousel](../carousel/post.md), [ProfileCarousel](../carousel/profile.md)), a swipeable media gallery, an onboarding pager. **Skip when** the position is a task-completion ratio (use [Progress](../progress/progress.md)), the pages need direct tap-to-jump navigation (dots here are non-interactive — use [Tabs](../tabs/tabs.md)), or the pager has only one page (the component renders nothing below two).
+
+**Layout inset.** `inline` — an inline element (`span`, `display: inline-flex`) exactly as wide as its dots, with no padding or fill of its own. It never stretches or centers itself; the host owns horizontal placement (the carousels center it via `align-self: center`) and the gap between its track and the dot row (`sys.layout.stack.md`).
+
+## Default
+
+Five pages with the third active. Dots are 6 × 6, fully rounded, `sys.layout.inline.sm` apart; the row is `aria-hidden` and renders at its intrinsic width — where it sits is the host's call.
+
+```preview
+pagination/default
+---
+import { Pagination } from '@teamblind-chorus/ui';
+
+<Pagination count={5} activeIndex={2} />
+```
+
+## Slots
+
+- **dot** *(decorative, one per page)* — 6 × 6 (`ref.space.75`), `sys.radius.full`. Active paints `sys.color.onSurface`; inactive paints `sys.color.outlineVariant`.
+
+## Anatomy
+
+| Slot | Token bindings |
+|------|----------------|
+| row  | inline element — `display: inline-flex`, intrinsic width, `sys.layout.inline.sm` gap, `aria-hidden`; horizontal placement belongs to the host |
+| dot  | 6 × 6 (`ref.space.75`), `sys.radius.full`; active `sys.color.onSurface`, inactive `sys.color.outlineVariant` |
+
+## Behavior
+
+- **Inline element.** A `span` with `display: inline-flex` and intrinsic width — the component paints no layout opinion beyond its own dot row. Centering under a pager (or any other placement) is a host binding: the carousels apply `align-self: center` on their own selector.
+- **Decorative.** The root carries `aria-hidden="true"`. Dots are not buttons; tapping one does not scroll. Because of this, the host MUST keep later pages reachable another way — focusable page contents in natural tab order, scroll-into-view on focus (see the carousel specs' `keyboardReach` rule).
+- **Host owns the index.** Pagination never observes scroll itself. The host derives `activeIndex` — typically an IntersectionObserver at a ~60% threshold on its scroll-snap targets — and the component paints it, clamped to `0..count-1`.
+- **Minimum two pages.** Renders nothing when `count` < 2; the host needs no conditional of its own.
+- **No emphasis axis.** A single appearance — active is `onSurface`, never a chromatic accent. Position is chrome, not a call to action.

package/agents/components/pagination/pagination.spec.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Pagination",
+  "family": "pagination",
+  "description": "Decorative dot-position indicator for one-page-at-a-time pagers. An inline element (`span`, `display: inline-flex`) sized to its dots — it never stretches or centers itself; the host owns horizontal placement (the carousels center it via `align-self: center`). Renders one 6px (`ref.space.75`) fully-rounded dot per page in a `sys.layout.inline.sm` row; the active dot paints `sys.color.onSurface`, the rest paint `sys.color.outlineVariant`. The row is presentational only (`aria-hidden`): the host pager (PostCarousel, ProfileCarousel, a media gallery) tracks the active index — typically via IntersectionObserver on its snap targets — and passes it down; tapping a dot does not navigate. Renders nothing when `count` < 2 — a one-page pager has no position to indicate.",
+  "element": "span",
+  "props": {
+    "count": {
+      "type": "number",
+      "default": 0,
+      "description": "Total number of pages — one dot renders per page. Below 2 the component renders nothing."
+    },
+    "activeIndex": {
+      "type": "number",
+      "default": 0,
+      "description": "Zero-based index of the active page. Clamped to `0..count-1`. Owned by the host pager (e.g. updated from an IntersectionObserver on its scroll-snap targets)."
+    }
+  },
+  "slots": {
+    "dot": {
+      "required": true,
+      "description": "One per page. 6 × 6 (`ref.space.75`), `sys.radius.full`. Active paints `sys.color.onSurface`; inactive paints `sys.color.outlineVariant`.",
+      "intrinsic": true
+    }
+  },
+  "sizing": {
+    "display": "inline-flex",
+    "displayNote": "Intrinsic width — the row is exactly as wide as its dots plus gaps. No `width`, no stretch, no self-centering; horizontal placement belongs to the host (the carousels apply `align-self: center` on their own selector).",
+    "dotSize": "ref.space.75",
+    "dotGap": "sys.layout.inline.sm",
+    "dotRadius": "sys.radius.full"
+  },
+  "appearance": {
+    "activeDot": "sys.color.onSurface",
+    "inactiveDot": "sys.color.outlineVariant"
+  },
+  "states": {
+    "default": { "note": "Pagination carries no lifecycle states — the active index is its visual state, and the dots are non-interactive." }
+  },
+  "behavior": {
+    "inlineElement": "An inline element — `span` with `display: inline-flex` and intrinsic width. The component never paints layout opinion beyond its own dot row; centering under a pager (or any other placement) is a host binding, not a Pagination one.",
+    "decorative": "The root carries `aria-hidden='true'`. Dots reflect the host pager's position only; they are not buttons and tapping one does not scroll. The host MUST keep later pages reachable another way (natural tab order + scroll-into-view on focus) — see the carousel specs' `keyboardReach` rule.",
+    "hostOwnsIndex": "Pagination never observes scroll itself. The host derives `activeIndex` (typically IntersectionObserver at a ~60% threshold on its snap targets) and re-renders; the component just paints it, clamped to `0..count-1`.",
+    "minCount": "Renders nothing when `count` < 2. The host does not need its own conditional around the component."
+  },
+  "forbidden": [
+    "Dots rendered as interactive controls (button / link, tap-to-navigate) — that needs a focusable, labelled tab-like contract this family deliberately does not carry; if navigation chrome is required, use a different component",
+    "Active dot painted with a chromatic primary / accent / brand tone — the indicator is position chrome, not emphasis; active is `sys.color.onSurface`, full stop",
+    "Pagination used as a step / completion indicator for a linear task — that role is `progress`",
+    "Numeric page labels, counters, or arrows composed into the row — the family is the dot row only; numbered pagination is a different pattern",
+    "Rendering the row for a single page (`count` < 2) by bypassing the built-in guard — a one-page pager has no position to indicate",
+    "Row stretched to the host column (`width: 100%` / block display) to center the dots from inside — the component is an intrinsic-width inline element; centering is the host's binding"
+  ]
+}

package/agents/components/profile-header/profile-header.md

@@ -1,5 +1,7 @@
 # Profile header
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/profile-header/profile-header.md`](../../../i18n/ko/schema/components/profile-header/profile-header.md)
+
 Identity block at the top of a profile detail screen — a full-bleed cover band, an overlapping circular [Thumbnail](../thumbnail/thumbnail.md) avatar, an entity name, a visibility + follower meta row, and a trailing follow [Toggle Button](../button/toggle.md). Same `profile` contract as [Profile carousel](../carousel/profile.md) (channel topic, user, company channel) — the carousel surfaces a fixed-shape card in a curated rail; the header is the page-level identity rung the rail's `See all` lands on.
 
 **Reach for this when** a profile detail route opens on a followable entity that needs a cover, an avatar, a single page-level heading, and a follow affordance. **Skip when** the screen is a feed list (use [Navigation bar/home](../navigation-bar/main.md) + [Feed](../feed/feed.md)), a settings or account drill-in (use [Navigation bar/page](../navigation-bar/sub.md) + [Nav card](../nav-card/nav-card.md)), or a curated profile rail (use [Carousel](../carousel/carousel.md) + [Profile carousel](../carousel/profile.md)).

package/agents/components/progress/progress.md

@@ -1,5 +1,7 @@
 # Progress
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/progress/progress.md`](../../../i18n/ko/schema/components/progress/progress.md)
+
 A single visual rung — 8px tall, fully rounded — that previews how far a long-running task has advanced. Determinate only: a filled indicator parks at the value's ratio. No emphasis axis: track paints with `sys.color.scrimSubtle` (the translucent inverse-tone scrim — ~8% black light, ~8% white dark); indicator paints in `inverseSurface` so the filled segment contrasts against the track regardless of theme.
 
 **Reach for this when** a screen holds a task long enough that the user would otherwise wonder if anything is happening — file uploads, onboarding step counters, background syncs, account migrations. **Skip when** the task resolves under 300ms, the wait is purely opaque (use [Skeleton](../skeleton/skeleton.md) for content placeholders, busy spinners for short opaque waits), or the metric is primary content rather than chrome (use a chart).

package/agents/components/side-sheet/side-sheet.md

@@ -1,5 +1,7 @@
 # SideSheet
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/side-sheet/side-sheet.md`](../../../i18n/ko/schema/components/side-sheet/side-sheet.md)
+
 Off-canvas content column anchored to the leading or trailing edge of the viewport. Pairs with [BottomSheet](../bottom-sheet/bottom-sheet.md) as the Sheet family's other anchor — BottomSheet for committed-sheet flows, SideSheet for off-canvas navigation columns, settings panes, channel directories, filter rails.
 
 **Reach for this when** an off-canvas column belongs next to the current page — a navigation drawer, a channel / topic / saved-item directory, a filter rail, a settings pane. **Skip when** the surface is a committed-sheet flow (use [BottomSheet](../bottom-sheet/bottom-sheet.md)), a confirmation prompt (use [Dialog](../dialog/dialog.md)), a labelled in-flow block (use [Section](../section/section.md)), or a permanent app-shell navigation (use [TabBar](../tab-bar/tab-bar.md) / [NavigationBar](../navigation-bar/navigation-bar.md)).

package/agents/components/skeleton/skeleton.md

@@ -1,5 +1,7 @@
 # Skeleton
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/skeleton/skeleton.md`](../../../i18n/ko/schema/components/skeleton/skeleton.md)
+
 A tonal placeholder block that previews where real content will render. Paints with a translucent `scrimSubtle` overlay (~8% black in light mode, ~8% white in dark) and a slow opacity pulse — visible on every host surface tier without colliding with a fixed neutral step. Three shapes — `text` (default 16-line block), `block` (image / card body), `circle` (avatar). Compose multiple Skeletons inside `SkeletonGroup` to mirror the loading content's rhythm.
 
 **Reach for this when** a list row, feed post, card cover, or avatar is being fetched and the host would otherwise paint empty. **Skip when** the wait is sub-300ms, the data is unavailable rather than loading (use an empty-state illustration), or the loading scope is the whole screen (use a centered progress indicator at page level).

package/agents/components/spinner/spinner.family.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "spinner",
+  "name": "Spinner",
+  "description": "Indeterminate loading indicator — a rotating arc in `sys.color.primary` that signals a short, progress-unknown wait (under ~1 second of expected delay) on a neutral host surface. Two rungs ride the `icon.*` size ladder: `medium` (`sys.icon.lg` / 24px, default) and `small` (`sys.icon.md` / 16px). An optional `label` slot lets a single line of loading copy sit beside the arc. Reserved to one Spinner per view — for content-shaped waits use `skeleton`, for a known ratio use `progress`. Single-spec family.",
+  "useCases": [
+    "sub-second indeterminate wait (button submit, inline action)",
+    "small surface where a skeleton would be heavier than the wait",
+    "centered first-paint loader before a screen's data resolves",
+    "loading copy beside a rotating indicator"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "inline",
+  "spec": "spinner.md",
+  "usage": {
+    "note": "indeterminate only — never bind it to a progress ratio (use Progress). Reserve to one Spinner per view. aria-label defaults to 'Loading'; pass a label child for visible loading copy beside the arc.",
+    "example": "<Spinner aria-label=\"Loading\" />"
+  },
+  "subcomponents": [
+    {
+      "slug": "spinner",
+      "spec": "spinner.spec.json",
+      "md": "spinner.md",
+      "default": true
+    }
+  ]
+}

package/agents/components/spinner/spinner.md

@@ -0,0 +1,98 @@
+# Spinner
+
+> 🇰🇷 한국어: [`i18n/ko/schema/components/spinner/spinner.md`](../../../i18n/ko/schema/components/spinner/spinner.md)
+
+An indeterminate loading indicator — a rotating arc in `sys.color.primary` over a faint `scrimSubtle` ring that signals a short, progress-unknown wait on a neutral host surface. Two rungs ride the `icon.*` ladder — `medium` (24px, default) and `small` (16px). Pass a `label` for a single line of loading copy beside the arc.
+
+**Reach for this when** a wait is brief and indeterminate (under ~1 second) — a button submit, an inline action, or a first-paint loader before a screen's data resolves — and a content-shaped placeholder would be heavier than the wait itself. **Skip when** the wait mirrors a known shape (use [Skeleton](../skeleton/skeleton.md)), the task has a measurable ratio (use [Progress](../progress/progress.md)), or the surface already shows another Spinner — reserve one per view.
+
+**Layout inset.** `inline` — Spinner ships no padding or container chrome of its own. It sits as a leaf at the size of its rung; the host owns centering and surrounding rhythm. An optional label sits beside the arc with `sys.layout.inline.sm` between them.
+
+## Default
+
+A 24px rotating arc. `role='status'` announces the loading state; `aria-label` defaults to `'Loading'`.
+
+```preview
+spinner/default
+---
+import { Spinner } from '@teamblind-chorus/ui';
+
+<Spinner aria-label="Loading" />
+```
+
+## Use cases
+
+### With label
+
+A single line of loading copy beside the arc. The label doubles as the accessible name, so `aria-label` is not needed.
+
+```preview
+spinner/with-label
+---
+import { Spinner } from '@teamblind-chorus/ui';
+
+<Spinner label="Loading…" />
+```
+
+### Small
+
+The 16px rung — for tight inline affordances (a button label, a form-field affix) where the 24px default would crowd.
+
+```preview
+spinner/small
+---
+import { Spinner } from '@teamblind-chorus/ui';
+
+<Spinner size="small" aria-label="Loading" />
+```
+
+### Centered
+
+A first-paint loader centered inside the surface that will hold the data. One Spinner per view.
+
+```preview
+spinner/centered
+---
+import { Spinner } from '@teamblind-chorus/ui';
+
+<div style={{ display: 'flex', justifyContent: 'center', padding: 'var(--sys-layout-container-xl)' }}>
+  <Spinner label="Loading…" />
+</div>
+```
+
+## Slots
+
+- **container** — inline-flex wrapper. Carries `role='status'` and the accessible name; holds the arc and the optional label, separated by `sys.layout.inline.sm`.
+- **arc** — the rotating ring. `sys.color.primary` foreground arc over a `sys.color.scrimSubtle` track ring, fully rounded, no stroke. Carries the spin animation. Decorative (`aria-hidden`).
+- **label** — optional single line of loading copy beside the arc. `sys.typo.body.sm`, `sys.color.onSurfaceVariant`.
+
+## Anatomy
+
+| Slot       | Token bindings |
+|------------|----------------|
+| container  | inline-flex, `sys.layout.inline.sm` gap between arc and label |
+| arc        | `sys.color.primary` foreground arc, `sys.color.scrimSubtle` track ring, `sys.radius.full`, no stroke |
+| medium     | `sys.icon.lg` (24px) diameter — the default rung |
+| small      | `sys.icon.md` (16px) diameter |
+| label      | `sys.typo.body.sm`, `sys.color.onSurfaceVariant` |
+
+## Sizes
+
+| Size     | Diameter            | When to reach |
+|----------|---------------------|---------------|
+| `medium` | `sys.icon.lg` (24px) | **Default**. Standalone or centered first-paint loaders. |
+| `small`  | `sys.icon.md` (16px) | Tight inline affordances — button labels, form-field affixes. |
+
+## States
+
+| State          | Animation                       | Notes |
+|----------------|---------------------------------|-------|
+| `default`      | `rotate 0.8s linear infinite`   | The arc spins continuously. Indeterminate — the rotation never reflects a value. |
+| reduced-motion | suppressed                      | Under `prefers-reduced-motion: reduce` the spin halts and the full ring shows statically. |
+
+## Behavior
+
+- **Indeterminate only.** The rotation never maps to a ratio — for a known percentage use [Progress](../progress/progress.md).
+- **One per view.** Reserve a single Spinner per screen; concurrent regional waits use [Skeleton](../skeleton/skeleton.md) or lift to one screen-level Spinner.
+- **Accessible name.** `role='status'` announces loading without interrupting focus. A visible `label` doubles as the name; otherwise `aria-label` (default `'Loading'`) carries it. The arc is decorative.
+- **Reduced motion.** Under `prefers-reduced-motion: reduce` the spin is suppressed; the full ring shows statically as a quiet loading mark.

package/agents/components/spinner/spinner.spec.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Spinner",
+  "family": "spinner",
+  "description": "A rotating arc that signals an indeterminate, sub-second wait on a neutral host surface. The arc paints in `sys.color.primary` as the foreground motion and spins continuously over a faint `sys.color.scrimSubtle` ring so the rotation reads on any surface tier. Two rungs ride the `icon.*` ladder — `medium` (`sys.icon.lg` / 24px, default) and `small` (`sys.icon.md` / 16px). An optional `label` slot places a single line of loading copy beside the arc. `role='status'` + an accessible name (`aria-label`, default `'Loading'`) announce the loading state. Indeterminate only — for a known ratio use Progress; for content-shaped waits use Skeleton.",
+  "element": "span",
+  "props": {
+    "size": {
+      "type": "enum",
+      "values": ["medium", "small"],
+      "default": "medium",
+      "description": "Selects the arc diameter off the `icon.*` ladder. `medium` paints at `sys.icon.lg` (24px); `small` at `sys.icon.md` (16px)."
+    },
+    "label": {
+      "type": "node",
+      "optional": true,
+      "description": "Optional loading copy rendered beside the arc in `sys.typo.body.sm` / `sys.color.onSurfaceVariant`. When present it also supplies the accessible name, so `aria-label` is not required."
+    },
+    "aria-label": {
+      "type": "string",
+      "optional": true,
+      "description": "Accessible label announced by screen readers. Defaults to `'Loading'`. Supply a more specific name (e.g. `'Signing in'`) when the wait scope is meaningful. Redundant when a visible `label` is passed."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Inline-flex wrapper carrying `role='status'` and the accessible name. Holds the arc and the optional label, separated by `sys.layout.inline.sm`.",
+      "intrinsic": true
+    },
+    "arc": {
+      "required": true,
+      "description": "The rotating ring. `sys.color.primary` foreground arc over a `sys.color.scrimSubtle` track ring, fully rounded, no stroke border. Carries the continuous spin animation. Decorative — `aria-hidden`.",
+      "intrinsic": true
+    },
+    "label": {
+      "required": false,
+      "description": "Optional single line of loading copy beside the arc. `sys.typo.body.sm`, `sys.color.onSurfaceVariant`.",
+      "omittedBehavior": "collapse"
+    }
+  },
+  "sizes": {
+    "medium": {
+      "diameter": "sys.icon.lg",
+      "labelTypo": "sys.typo.body.sm",
+      "gap": "sys.layout.inline.sm"
+    },
+    "small": {
+      "diameter": "sys.icon.md",
+      "labelTypo": "sys.typo.body.sm",
+      "gap": "sys.layout.inline.sm"
+    }
+  },
+  "appearances": {
+    "default": {
+      "arc": "sys.color.primary",
+      "track": "sys.color.scrimSubtle",
+      "label": "sys.color.onSurfaceVariant",
+      "note": "The only appearance. The foreground arc paints `sys.color.primary` for the motion accent; the track ring paints `sys.color.scrimSubtle` (a faint inverse-tone scrim — ~8% black light / ~8% white dark) so the rotation reads on any host surface tier. Spinner has no emphasis axis — for a higher-attention loading mark the emphasis belongs in adjacent copy, not in a chromatic arc swap."
+    }
+  },
+  "states": {
+    "default": {
+      "animation": "chorus-spinner-rotate 0.8s linear infinite",
+      "note": "The arc rotates continuously at 0.8s per turn (well below the WCAG flash threshold — rotation modulates position, not luminance). Indeterminate: the rotation never reflects a value. The animation respects `prefers-reduced-motion: reduce` — the spin halts and the full ring is shown statically as a quiet loading mark."
+    }
+  },
+  "behavior": {
+    "ariaStatus": "Container carries `role='status'` and the accessible name (visible `label` or `aria-label`, default `'Loading'`) so screen readers announce the loading state without yanking focus. The arc is decorative (`aria-hidden`).",
+    "reducedMotion": "Under `@media (prefers-reduced-motion: reduce)` the spin is suppressed; the full ring shows statically as a quiet loading mark.",
+    "singleInstance": "Reserve one Spinner per view. Concurrent regional waits stack visual noise — lift to a single screen-level Spinner or switch the inner waits to Skeleton.",
+    "labelComposition": "Pass `label` for visible loading copy beside the arc; it doubles as the accessible name. Without a label, `aria-label` (default `'Loading'`) carries the announcement."
+  },
+  "forbidden": [
+    "Spinner bound to a known progress ratio / percentage — indeterminate only; a determinate value belongs to `progress`",
+    "more than one Spinner visible in a single view — reserve to one per view; concurrent regional waits use `skeleton` or lift to a single screen-level Spinner",
+    "Spinner used as a content-shaped placeholder (list row, feed card, avatar) — that role is `skeleton`, which mirrors the footprint of the data being fetched",
+    "arc painted with a non-token hex / raw px diameter — the arc tone is `sys.color.primary` and the diameter rides the `icon.*` ladder (`sys.icon.md` / `sys.icon.lg`)",
+    "shimmer / gradient sweep on the arc — Spinner modulates rotation only (one motion axis keeps it readable under the reduced-motion fallback)",
+    "arc track or ring drawn with a `border:` — the ring draws as a `box-shadow` / conic fill, not a layout stroke"
+  ]
+}

package/agents/components/status-tag/status-tag.md

@@ -1,5 +1,7 @@
 # Status tag
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/status-tag/status-tag.md`](../../../i18n/ko/schema/components/status-tag/status-tag.md)
+
 A small inline status pill — a tonal mark sized for the trailing edge of a row label. Two **appearances**: `neutral` (quiet informational default) and `error` (rejection / blocked). Decorative — never interactive.
 
 **Reach for this when** a row label needs a short state annotation inline — "pending" next to a user channel, "rejected" next to a failed approval, "draft" next to an in-progress post. **Skip when** the state is the row's primary content (use [List/standard](../list/standard.md) with `supportingText`), when the mark must be tappable (host row owns the click target), inside a chip row (use [chip/filter](../chip/filter.md) or [chip/tag](../chip/tag.md)), or when the mark names *who the person is* rather than a workflow state — 채널장 / 현직자 belong to [badge/role](../badge/role.md).

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

@@ -1,5 +1,7 @@
 # Suggestion list
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/suggestion-list/suggestion-list.md`](../../../i18n/ko/schema/components/suggestion-list/suggestion-list.md)
+
 A vertically-stacked block of follow-able recommendations rendered as a swipeable pager. One page shows three [list/entry](../list/entry.md)-shaped rows at the `xlarge` rung (56px [Thumbnail](../thumbnail/thumbnail.md), label + stacked `secondary` followers + `description`, trailing [Toggle Button](../button/toggle.md)); the next page peeks at the trailing edge to invite the swipe. Anatomy is entity-agnostic — channels, people, companies, topics share one shape.
 
 **Reach for this when** a follow-able set is best surfaced as a peek of three with horizontal paging — recommended channels, people you may know, suggested companies. **Skip when** the full set should scan vertically with no pager (use [DirectoryList](../directory-list/directory-list.md)), the rail is a label-only nav strip ([AvatarRail](../avatar-rail/avatar-rail.md)), or the surface needs fixed-width profile cards ([Profile carousel](../carousel/profile.md)).

package/agents/components/switch/switch.md

@@ -1,5 +1,7 @@
 # Switch
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/switch/switch.md`](../../../i18n/ko/schema/components/switch/switch.md)
+
 A binary active/inactive control — a pill-shaped track with a circular thumb that translates between ends. **Inactive** reads as a `scrimSubtle` track with an `outlineVariant` hairline and a fixed-white thumb; **active** paints the track in `primary` so the contract reads chromatically without an inline label.
 
 **Reach for this when** a setting commits the moment it changes — notifications, privacy toggles, *show in feed*, instant-commit list trailing. **Skip when** the commit needs confirmation (use [Button](../button/button.md) + [Dialog](../dialog/dialog.md)), when the user picks one of several options ([List/radio](../list/radio.md), [Tabs](../tabs/tabs.md)), or when destructive — Switch carries no undo.

package/agents/components/switch/switch.spec.json

@@ -88,6 +88,15 @@
     "pressed": {
       "overlay": { "color": "label", "opacity": "sys.state.pressed" }
     },
+    "focused": {
+      "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 — a three-layer outward ring on the track's outer edge, with no state-overlay tint (the ring alone carries focus here). Mirrors the `focusIndicator` block for spec-only renderers. Composes over the lifecycle state the control is in."
+    },
     "disabled": {
       "containerOpacity": "sys.state.disabled",
       "pointerEvents": "none",

package/agents/components/tab-bar/tab-bar.md

@@ -1,5 +1,7 @@
 # Tab bar
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/tab-bar/tab-bar.md`](../../../i18n/ko/schema/components/tab-bar/tab-bar.md)
+
 The bottom tab bar — a horizontal strip pinned to the bottom of the app exposing top-level destinations (Home / Company / Explore / Jobs / Notifications) in one tap. Each item stacks a 24px glyph above a 10/Regular label; active items show the filled companion glyph at `onSurface`, inactive render the outline at `onSurfaceVariant`. An item may opt into `appearance="primary"` to render a tile-shaped commit affordance — the conventional **Create** entry at the trailing end.
 
 **Reach for this when** you need persistent top-level navigation on a mobile-shaped viewport. **Skip when** the destinations belong inside a single surface — use [Tabs](../tabs/underline.md) — or when the chrome must float — use [FAB](../button/fab.md).

package/agents/components/tab-bar/tab-bar.spec.json

@@ -142,6 +142,22 @@
       "description": "Active press on the item. State layer fills the slot, painted with `onSurface` at `sys.state.pressed` (12%).",
       "stateLayerFill": "color-mix(sys.color.onSurface, sys.state.pressed)"
     },
+    "focused": {
+      "stateLayerFill": "color-mix(sys.color.onSurface, 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. State layer fills the slot with `onSurface` at `sys.state.focus` (12%); the three-layer ring is forced inward (adjacent items are flush under flex:1 1 0). Mirrors the `focusIndicator` block for spec-only renderers. Single-focus: at most one item holds the ring."
+    },
     "active": {
       "description": "Currently selected destination. Filled glyph (`activeIcon`) + label, both at `onSurface`. Carries `aria-current='page'`. No persistent state layer — only hover / pressed / focus paint."
     },

package/agents/components/tabs/rounded.md

@@ -1,5 +1,7 @@
 # Rounded
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/tabs/rounded.md`](../../../i18n/ko/schema/components/tabs/rounded.md)
+
 Rounded-rectangle tab row — each tab a self-contained chip with a required leading icon and label. Shares chrome with [Segmented](./segmented.md) and [Filter chip](../chip/filter.md) verbatim; the single divergence is corner radius, which steps from `sys.radius.full` (capsule) to `sys.radius.md` (8) — reads as a soft rounded rectangle, not a pill.
 
 **Reach for this when** the row is a sort/filter switcher inside content. **Skip when** the row anchors content sections — use [Underline](./underline.md) — or when it's an in-place mode change — use [Segmented](./segmented.md).

package/agents/components/tabs/rounded.spec.json

@@ -106,6 +106,25 @@
         "opacity": "sys.state.pressed"
       }
     },
+    "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 tab is in; never via plain mouse click."
+    },
     "disabled": {
       "overlay": null,
       "containerOpacity": "sys.state.disabled",

package/agents/components/tabs/segmented.md

@@ -1,5 +1,7 @@
 # Segmented
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/tabs/segmented.md`](../../../i18n/ko/schema/components/tabs/segmented.md)
+
 The inline view-mode toggle — a row of mutually-exclusive selectors for in-place mode changes (List ↔ Grid, Day ↔ Week ↔ Month).
 
 **Reach for this when** the segments swap the *same* content's view or range in place — List ↔ Grid, Day ↔ Week ↔ Month. **Skip when** segments switch between *different* panels ([Underline](./underline.md)), multiple values can co-select ([Filter chip](../chip/filter.md)), or the rung is a single-select picker over a long list ([Radio list](../list/radio.md)).

package/agents/components/tabs/tabs.md

@@ -1,5 +1,7 @@
 # Tabs
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/tabs/tabs.md`](../../../i18n/ko/schema/components/tabs/tabs.md)
+
 A horizontal row of mutually-exclusive selections — exactly one tab is active, and selecting one swaps the surrounding panel. Sub-flavors: **Underline** is the canonical content-section switcher; **Segmented** is the inline view-mode toggle whose chrome delegates to [Filter chip](../chip/filter.md).
 
 **Layout inset.** `full-bleed` — sits as a direct child of the page shell (or any surface that pays the gutter) and stretches edge-to-edge inside it. The tabs rail pays its own internal padding via `layout.container.*`; do **not** wrap it in another `padding-inline` / `px-*` / `style={{ padding: … }}` div, or the page rail double-pays. Inside a bounded surface (Card / Dialog / BottomSheet / Sheet), apply the negative-margin opt-out — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).

package/agents/components/tabs/underline.md

@@ -1,5 +1,7 @@
 # Underline
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/tabs/underline.md`](../../../i18n/ko/schema/components/tabs/underline.md)
+
 The canonical content-section switcher — a row of tabs anchored above a panel, with a 2px `onSurface` indicator that slides along the active tab's bottom edge.
 
 **Reach for this when** moving between peer panels of the same surface. **Skip when** the row is an in-place mode change — use [Segmented](./segmented.md) instead.

package/agents/components/tabs/underline.spec.json

@@ -103,6 +103,25 @@
         "opacity": "sys.state.pressed"
       }
     },
+    "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 tab is in; never via plain mouse click."
+    },
     "disabled": {
       "overlay": null,
       "containerOpacity": "sys.state.disabled",

package/agents/components/thumbnail/thumbnail.md

@@ -1,5 +1,7 @@
 # Thumbnail
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/thumbnail/thumbnail.md`](../../../i18n/ko/schema/components/thumbnail/thumbnail.md)
+
 A circular image — the unit that identifies a channel, a feed author, or any small-rung image. Two optional badges ride without changing footprint: an **update dot** top-right and a **logo badge** bottom-right. A pure visual primitive — no label of its own.
 
 **Reach for this when** the host needs to identify an entity at a glance — channel avatar in a list row, feed author block, AvatarRail item, NavigationBar leading. **Skip when** the surface is a labelled icon glyph (use [Icon Button](../button/icon.md)) or a sub-brand identity at fixed inline scale ([NavCard](../nav-card/nav-card.md)'s logo slot).

package/agents/components/toast/toast.md

@@ -1,5 +1,7 @@
 # Toast
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/toast/toast.md`](../../../i18n/ko/schema/components/toast/toast.md)
+
 A transient confirmation strip that floats above the page after a user action lands — saved, copied, sent, retried. Inverse-toned by default so the message contrasts with any underlying page tier; content-driven width up to a 400 cap.
 
 **Reach for this when** you need to confirm a system outcome the user just triggered — saved, copied, sent, retried. **Skip when** the message is contextual to the content itself (use [Banner](../banner/banner.md)), or the surface is a committed confirmation prompt (use [Dialog](../dialog/dialog.md)).

package/agents/components/tooltip/tooltip.md

@@ -1,5 +1,7 @@
 # Tooltip
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/tooltip/tooltip.md`](../../../i18n/ko/schema/components/tooltip/tooltip.md)
+
 A trigger-anchored explanation bubble — a small contrast-toned surface with a caret that points at the host. Reach for it to surface a label or short hint that does not fit on the trigger ("Manage" on an icon button, a coach-mark). Prefer [Banner](../banner/banner.md) when the message belongs inline in the reading flow, and [Toast](../toast/toast.md) when it confirms a recent user action.
 
 **Layout inset.** `bounded-surface` — popover shell anchored to a trigger element. Owns its outer padding and trigger-relative placement; not subject to the page shell's `layout.page.*` gutter. Mount via a portal at the document root and position relative to the trigger. See [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).

package/agents/compose.md

@@ -17,7 +17,7 @@ The recipes below answer the five compositional situations every product surface
 | `sys.layout.page.lg` (24→40px) | Marketing / editorial / landing. |
 | `sys.layout.page.xl` (40→64px) | Showcase heroes only. |
 
-**Paid once at the page shell.** All **eleven full-bleed families** inherit it — `navigation-bar`, `profile-header`, `tab-bar`, `tabs`, `section`, `feed`, `list`, `accordion` (list sub), `suggestion-list`, `avatar-rail`, `chip` (group). Never re-pay `padding-inline` on the child. Inline cards (`banner`, `nav-card`) are NOT in this list — they don't claim the page rail themselves; the host (page shell at the top level, or another container when wrapped) pays their horizontal inset for them. See LOVABLE.md §A.4.
+**Paid once at the page shell.** All **thirteen full-bleed families** (`family.json#layoutInset` is authoritative) inherit it — `avatar-rail`, `carousel`, `directory-list`, `divider`, `feed`, `header`, `list`, `nav-list`, `navigation-bar`, `profile-header`, `suggestion-list`, `tab-bar`, `tabs` — plus the `feed-ad` (feed sub) and `accordion` (list sub) that inherit from their parent. Never re-pay `padding-inline` on the child. `chip` is `inline`, but a chip *group* (filter rail) is rail-responsible — place it like a full-bleed child (no padding wrapper). Inline cards (`banner`, `nav-card`) are NOT in this list — they don't claim the page rail themselves; the host (page shell at the top level, or another container when wrapped) pays their horizontal inset for them. See LOVABLE.md §A.4.
 
 ### Surface interior padding
 
@@ -142,7 +142,7 @@ DESIGN.md rules condensed to a single line each. Read as **immediate-reject** tr
 4. **Surface tier ≤ 2 levels per screen.** `surface` plus one `surface*Container` rung is the cap. A third nested surface tone reads muddy — promote one to a different family (Banner, Card, Section header) instead of layering.
 5. **Chip / pill / avatar radius is always `radius.full`.** A 4px-rounded "chip" is a card; pick one component. Likewise a 999-rounded "card" reads as a chip.
 6. **Banner role decides the fill.** Informational → `sys.color.primaryContainer`. Promotional → `sys.color.surfaceContainerLow` (with optional brand accent on the leading icon, *not* the background). Error notice → `sys.color.errorContainer`. **`brandContainer` is reserved for promotional tinted strips, not default banners.**
-7. **Page inset is paid once at the page shell.** Every `full-bleed` family (Header — both `<Header>` and `<SubHeader>` — List, Feed, FeedAd, Carousel, AvatarRail, Divider, DirectoryList, NavList, SuggestionList, ProfileHeader, Chip group, NavigationBar, TabBar, Tabs) stretches edge-to-edge and pays its own row inset internally — never wrap one in a padded container or pass it `padding-inline`, or it double-pays the rail and lands at a different margin than its siblings. `Banner` / `nav-card` are **inline** (host owns the inset), not full-bleed. See `family.json#layoutInset` — the authoritative per-family value.
+7. **Page inset is paid once at the page shell.** Every `full-bleed` family (AvatarRail, Carousel, DirectoryList, Divider, Feed — plus its FeedAd sub — Header (both `<Header>` and `<SubHeader>`), List — plus its accordion sub — NavList, NavigationBar, ProfileHeader, SuggestionList, TabBar, Tabs) stretches edge-to-edge and pays its own row inset internally — never wrap one in a padded container or pass it `padding-inline`, or it double-pays the rail and lands at a different margin than its siblings. `Banner` / `nav-card` are **inline** (host owns the inset), not full-bleed; `Chip` is **inline** too, but a chip *group* is rail-responsible — place it like a full-bleed child. See `family.json#layoutInset` — the authoritative per-family value.
 8. **Nesting tightens, never widens.** Parent `container.md` → child `container.sm` → grandchild `container.xs`. Inverting reads as compression, not hierarchy.
 9. **Spec slot grammar is closed.** If a slot is not declared in `spec.json#slots`, it does not exist. Do not synthesize new slots, do not pass `className` / `style` overrides.
 10. **FAB count ≤ 1 per screen.** Create is the single canonical commit — additional FABs dilute the affordance.
@@ -193,7 +193,7 @@ If a step has no good match — that's a **Chorus gap**, not a license to invent
 
 ## When you go custom (no Chorus family fits)
 
-The LEGO ladder didn't surface a fit and you've genuinely exhausted visual-reuse on the 13 `"open"` families — you're building a custom primitive (small hint card, inline annotation, narrow aside). **Component went flexible; tokens did not.** With no Chorus spec to deny you, every literal value you type is either a token resolution or a violation.
+The LEGO ladder didn't surface a fit and you've genuinely exhausted visual-reuse on the `"open"` families (count owned by LOVABLE §C / `family.json#visualReuse`) — you're building a custom primitive (small hint card, inline annotation, narrow aside). **Component went flexible; tokens did not.** With no Chorus spec to deny you, every literal value you type is either a token resolution or a violation.
 
 The drift shape this section guards: a custom div where `background` is a token (because color rules are well-internalized) but `gap`, `padding`, `fontSize`, `lineHeight`, `borderRadius` are raw px (because the "off-scale px" rule lives in prose, not in concrete examples). Five literals, five violations — *"I used the color token"* is not a partial pass.