@teamblind-chorus/ui 1.0.1 → 1.2.0

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

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

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

@@ -0,0 +1,87 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "EmptyState",
+  "family": "empty-state",
+  "description": "The centered composition a surface paints when it holds no data yet — an optional monochrome illustration, a required headline, optional body copy, and an optional primary CTA — stacked and centered inside the space the real content would occupy. Three lines of copy at most: what the surface is for, why it is empty, and the one action that fills it (the CTA). Reach for it whenever a feed, list, inbox, or search result would otherwise paint blank; the system hard-rule forbids leaving a no-data surface empty. Distinct from Skeleton (an in-flight tonal placeholder for data that is loading), this is the durable zero-state surface.",
+  "element": "div",
+  "props": {
+    "illustration": {
+      "type": "node",
+      "optional": true,
+      "description": "Optional leading glyph or illustration, centered above the headline. Sized to a `ref.space.600` (48) box — larger than `sys.icon.lg` (24), realizing DESIGN.md's `icon.xl` or larger intent (no `icon.xl` icon-size rung exists; the icon scale stops at `lg`). Painted in `sys.color.onSurfaceVariant` via `currentColor` so it reads as quiet, monochrome chrome — illustrations stay monochrome unless they carry deliberate brand-moment intent. Separated from the headline by `sys.layout.stack.sm` (12)."
+    },
+    "headline": {
+      "type": "node",
+      "required": true,
+      "description": "The required lead line. `sys.typo.heading.sm` in `sys.color.onSurface`. Names what the surface is for / why it is empty in one short line (e.g. 'No posts yet')."
+    },
+    "body": {
+      "type": "node",
+      "optional": true,
+      "description": "Optional supporting line below the headline. `sys.typo.body.sm` in `sys.color.onSurfaceVariant`, separated from the headline by `sys.layout.stack.2xs` (4). One sentence — the second of the three lines (e.g. 'Conversations you start or join will appear here')."
+    },
+    "action": {
+      "type": "object",
+      "optional": true,
+      "description": "{ label, href?, onClick? } — the primary CTA. Renders a default-size primary `Button` (the surface's primary action — the one thing that fills the empty surface). Placed below the body with a `sys.layout.stack.md` (16) gap. There is NO `cta` slot to fill with a custom button; pass the action object so the primary Button is composed for you."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Centered flex column holding the whole composition. `align-items: center`, `text-align: center`. Ships no surface fill or chrome of its own — it sits inside the host surface that would otherwise hold the data. `role='status'` so assistive tech announces the empty state without yanking focus.",
+      "intrinsic": true
+    },
+    "illustration": {
+      "required": false,
+      "description": "Optional centered glyph / illustration above the headline. `ref.space.600` (48) box, painted in `sys.color.onSurfaceVariant` (monochrome). `sys.layout.stack.sm` (12) below it to the headline.",
+      "accepts": ["icon"]
+    },
+    "headline": {
+      "required": true,
+      "description": "Required headline line. `sys.typo.heading.sm` / `sys.color.onSurface`.",
+      "accepts": ["text"]
+    },
+    "body": {
+      "required": false,
+      "description": "Optional supporting line. `sys.typo.body.sm` / `sys.color.onSurfaceVariant`. `sys.layout.stack.2xs` (4) above it from the headline.",
+      "accepts": ["text"]
+    },
+    "action": {
+      "required": false,
+      "description": "Optional primary CTA. A default-size primary `Button` composed from the `action` object. `sys.layout.stack.md` (16) above it from the body.",
+      "accepts": ["button"]
+    }
+  },
+  "sizing": {
+    "containerAlign": "center",
+    "illustrationSize": "ref.space.600",
+    "illustrationColor": "sys.color.onSurfaceVariant",
+    "illustrationGap": "sys.layout.stack.sm",
+    "headlineTypo": "sys.typo.heading.sm",
+    "headlineColor": "sys.color.onSurface",
+    "bodyTypo": "sys.typo.body.sm",
+    "bodyColor": "sys.color.onSurfaceVariant",
+    "bodyGap": "sys.layout.stack.2xs",
+    "actionGap": "sys.layout.stack.md"
+  },
+  "appearance": {
+    "illustration": "sys.color.onSurfaceVariant",
+    "headline": "sys.color.onSurface",
+    "body": "sys.color.onSurfaceVariant",
+    "note": "No emphasis axis — EmptyState has one quiet appearance. The illustration and body sit in the muted `onSurfaceVariant` tone; the headline steps up to `onSurface`. The only chromatic emphasis is the CTA, which is a primary `Button` (its own `sys.color.primary` fill) so the single fill-the-surface action reads as primary both in intent and visually."
+  },
+  "behavior": {
+    "centered": "The whole composition is centered (block + inline) inside the host surface that would otherwise hold the data. EmptyState owns no surface fill — the host supplies the surface tier and the bounding box; EmptyState only centers its column inside it.",
+    "role": "Container carries `role='status'` so the empty state is announced to assistive tech without grabbing focus.",
+    "ctaComposition": "The CTA is not a free slot — pass `action={{ label, href?/onClick? }}` and EmptyState composes a default-size primary Button. This keeps the 'one primary action' rule enforced (one CTA, primary appearance) rather than letting callers drop in an arbitrary control."
+  },
+  "forbidden": [
+    "a no-data surface left blank — every empty surface paints an EmptyState (illustration optional, headline + the one fill action required by the copy rule); the system hard-rule forbids an unaddressed empty surface",
+    "a dead-end empty state with no path forward — when the surface has a fill action, omit neither the body's explanation nor the `action` CTA; do not strand the user on a blank wall with only a headline",
+    "more than three lines of copy — headline + body must read as at most three lines total (what the surface is for · why it is empty · the one action that fills it); longer prose belongs in a Banner or a help surface",
+    "the CTA rendered as anything but a default-size primary Button — the fill action is the surface's primary action and must read as primary; do not down-rank it to a text or outlined button, and do not render two competing CTAs",
+    "EmptyState used as a loading placeholder for data that is still arriving — that is `skeleton` (an in-flight tonal block). EmptyState is the durable no-data surface, not a transient one",
+    "the illustration painted in a chromatic tone for non-brand empty states — it stays monochrome `sys.color.onSurfaceVariant` unless it deliberately carries a brand moment"
+  ]
+}

package/agents/components/feed/ad.md

@@ -1,5 +1,7 @@
 # Ad
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/feed/ad.md`](../../../i18n/ko/schema/components/feed/ad.md)
+
 Sub-component of the [Feed](./feed.md) family. A sponsored placement riding the same scrolling column as [Feed · Post](./post.md). The header trades a channel/author row for a brand row (32-rung [Thumbnail](../thumbnail/thumbnail.md) + brand name + `Sponsored` subtitle + trailing close affordance); the body stays the same shape as Feed's title + excerpt; hero media and CTA bond into a single rounded slab at the foot. No engagement row — ads are not authored content.
 
 **Reach for this when** a sponsored placement must ride inline in the feed column alongside authored posts — a promoted brand post, an in-feed ad unit. **Skip when** the content is authored by a user (use [Feed · Post](./post.md)) or the promotion belongs in a dedicated surface outside the feed stream.

package/agents/components/feed/feed.md

@@ -1,5 +1,7 @@
 # Feed
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/feed/feed.md`](../../../i18n/ko/schema/components/feed/feed.md)
+
 The unit of a scrolling stream. The family covers two card shapes that ride the same column: **[Post](./post.md)** — the authored content card (channel header, title + body, optional thumbnail / poll / offer / citation / mention, engagement footer); **[Ad](./ad.md)** — the sponsored placement (brand row, optional title + body, a hero + CTA slab, no engagement row).
 
 Editorial collections of popular posts ride alongside Feed cards via the [Section · Post Carousel](../carousel/post.md) sub of the [Carousel](../carousel/carousel.md) family — that pair owns the curated-collection placement, not Feed itself.

package/agents/components/feed/post.md

@@ -1,5 +1,7 @@
 # Post
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/feed/post.md`](../../../i18n/ko/schema/components/feed/post.md)
+
 Sub-component of the [Feed](./feed.md) family. The authored-content card — the unit of a scrolling feed. Composes a flag, author row, body block (title + clamped excerpt + optional thumbnail), optional inline modules (poll, offer, citation, mention), and an engagement footer.
 
 **Reach for this when** rendering a single user-authored entry — text post, poll, offer evaluation, link share. **Skip when** the placement is sponsored ([Feed · Ad](./ad.md)) or the row is a metric summary rather than authored content.

package/agents/components/form-field/form-field.md

@@ -1,6 +1,8 @@
 # Form field
 
-The text-entry primitives — controls the user types into or picks a value from. **Input** is single-line text; **Search Bar** is its search-shaped sibling; **Select** is the Input-shaped picker that opens a sheet. Cross-family contract: bordered surface-toned container, hairline rest stroke that thickens while active, `error` appearance re-tones the whole field.
+> 🇰🇷 한국어: [`i18n/ko/schema/components/form-field/form-field.md`](../../../i18n/ko/schema/components/form-field/form-field.md)
+
+The text-entry primitives — controls the user types into or picks a value from. **Input** is single-line text; **Search Bar** is its search-shaped sibling; **Select** is the Input-shaped picker that opens a sheet. Cross-family contract: bordered surface-toned container, hairline rest stroke that thickens while active, `error` appearance re-tones the whole field. The trailing clear ("×") is an independent nested action — while the pointer hovers / presses it, the field's own hover stroke and pressed overlay are suppressed so the large field never reads as pressed alongside the small control. (The Select chevron is exempt: it fires the same action as clicking the field, so it lights the field.)
 
 **Layout inset.** `inline` — slot atom. No page-rail responsibility; the surrounding container places it. Sits inside a labelled form layout (vertical FormField stack) or another component's slot (NavigationBar centre for Search, BottomSheet body for quick-entry) — never a sibling of `full-bleed` page rows. The form column pays the page gutter, not the field.
 

package/agents/components/form-field/input.md

@@ -1,5 +1,7 @@
 # Input
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/form-field/input.md`](../../../i18n/ko/schema/components/form-field/input.md)
+
 Single-line text field — a bordered, transparent-fill box for short values. Optional `label`, `helper`, or `maxLength` compose it into a labeled group; `appearance="error"` re-tones fill, text, and stroke.
 
 **Reach for this when** capturing a short single-line value — name, email, search query, comment subject. **Skip when** the value is multi-line (use a textarea), a one-of-many selection (use a select), or a free-form search with built-in results (use the [search](./search.md) sub).

package/agents/components/form-field/input.spec.json

@@ -151,15 +151,23 @@
       "overlay": {
         "color": "text",
         "opacity": "sys.state.pressed"
-      }
+      },
+      "nestedActionScope": "The pressed overlay (and hover stroke) is suppressed while the pointer presses / hovers the trailing clear button — that '×' is an independent nested action, so the small control owns the state and the large field does not also read as pressed. The visual-state boundary matches the action boundary."
     },
     "active": {
+      "isFocusState": true,
       "overlay": null,
       "border": "borderActive",
       "strokeWeight": "activeStrokeWeight",
       "caret": "visible",
       "showsClearWhenValue": true,
-      "note": "The stroke steps from its rest `hairline` (1px) to `activeStrokeWeight` (2px) and re-tones to `borderActive` — but it is an inset `box-shadow`, not a `border`, so the box model is untouched: the field's footprint, caret, and text position are pixel-stable as it goes active. Nothing reflows. The clear button is shown only in this state (and only when the value is non-empty)."
+      "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": "This IS the field's keyboard/input-focus state — `active` (caret visible, input engaged) and `:focus-visible` coincide for a text field, so there is no separate `focused` state; the focus ring described here (and in the parallel `focusIndicator` block) is the focus affordance. The stroke steps from its rest `hairline` (1px) to `activeStrokeWeight` (2px) and re-tones to `borderActive` — but it is an inset `box-shadow`, not a `border`, so the box model is untouched: the field's footprint, caret, and text position are pixel-stable as it goes active. Nothing reflows. The clear button is shown only in this state (and only when the value is non-empty)."
     },
     "disabled": {
       "overlay": null,

package/agents/components/form-field/search.md

@@ -1,5 +1,7 @@
 # Search bar
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/form-field/search.md`](../../../i18n/ko/schema/components/form-field/search.md)
+
 Search-shaped single-line field — sibling of [Input](./input.md) with a leading `SearchIcon` and `sys.radius.full` pill corner. Box, stroke, placeholder rule, clear button, and focus ring inherited from Input unchanged. **Bare box only — no `label`, `helper`, `maxLength`, or `error` appearance.** Error reporting belongs to a labelled Input.
 
 **Reach for this when** the rung is a query against an open set — directory search, post filter, command palette entry. **Skip when** the value is a labelled form field ([Input](./input.md)), the user picks from a known closed set ([Select](./select.md)), or the surface needs error reporting (a bare search rung has nowhere to host it — use a labelled [Input](./input.md)).

package/agents/components/form-field/search.spec.json

@@ -92,15 +92,23 @@
       "overlay": {
         "color": "text",
         "opacity": "sys.state.pressed"
-      }
+      },
+      "nestedActionScope": "The pressed overlay (and hover stroke) is suppressed while the pointer presses / hovers the trailing clear button — that '×' is an independent nested action, so the small control owns the state and the large field does not also read as pressed. The visual-state boundary matches the action boundary."
     },
     "active": {
+      "isFocusState": true,
       "overlay": null,
       "border": "borderActive",
       "strokeWeight": "activeStrokeWeight",
       "caret": "visible",
       "showsClearWhenValue": true,
-      "note": "The stroke steps from its rest `hairline` (1px) to `activeStrokeWeight` (2px) and re-tones to `borderActive` — but it is an inset `box-shadow`, not a `border`, so the box model is untouched: the field's footprint, caret, and text position are pixel-stable as it goes active. Nothing reflows. The clear button is shown only in this state (and only when the value is non-empty)."
+      "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": "This IS the field's keyboard/input-focus state — `active` (caret visible, input engaged) and `:focus-visible` coincide for a text field, so there is no separate `focused` state; the focus ring described here (and in the parallel `focusIndicator` block) is the focus affordance. The stroke steps from its rest `hairline` (1px) to `activeStrokeWeight` (2px) and re-tones to `borderActive` — but it is an inset `box-shadow`, not a `border`, so the box model is untouched: the field's footprint, caret, and text position are pixel-stable as it goes active. Nothing reflows. The clear button is shown only in this state (and only when the value is non-empty)."
     },
     "disabled": {
       "overlay": null,

package/agents/components/form-field/select.md

@@ -1,5 +1,7 @@
 # Select
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/form-field/select.md`](../../../i18n/ko/schema/components/form-field/select.md)
+
 Input-shaped picker — same box, label, helper, and error re-tone as [Input](./input.md), but read-only and ending in an `ArrowDownIcon` chevron. Clicking opens a Bottom Sheet with the option list; chosen value is echoed back through `value`.
 
 **Reach for this when** the user picks one value from a known set that's too long for inline chips — country, currency, sort order, equity tier. **Skip when** the value is free text ([Input](./input.md)), the user searches an open set ([Search bar](./search.md)), or the list is short enough to surface inline as a [Radio list](../list/radio.md).

package/agents/components/form-field/select.spec.json

@@ -150,9 +150,17 @@
       }
     },
     "active": {
+      "isFocusState": true,
       "overlay": null,
       "border": "borderActive",
-      "strokeWeight": "activeStrokeWeight"
+      "strokeWeight": "activeStrokeWeight",
+      "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": "This IS the trigger's keyboard-focus / open state — `:focus-visible` and the engaged (open) state coincide for the select trigger, so there is no separate `focused` state; the focus ring described here (and in the parallel `focusIndicator` block) is the focus affordance. The stroke re-tones to `borderActive` at `activeStrokeWeight` (2px) as an inset box-shadow, pixel-stable (no reflow)."
     },
     "disabled": {
       "overlay": null,

package/agents/components/form-field/textarea.md

@@ -1,5 +1,7 @@
 # Textarea
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/form-field/textarea.md`](../../../i18n/ko/schema/components/form-field/textarea.md)
+
 Multi-line cousin of [input](./input.md) — identical chrome contract (transparent fill, inset box-shadow stroke, optional `label` / `helper` / `maxLength` group rungs); the inner element is a `<textarea>` with configurable `rows` (default 4) and vertical-only resize.
 
 **Reach for this when** the value naturally spans multiple lines: compose surfaces, bug reports, profile bios, comment composers. **Skip when** the value is single-line ([input](./input.md)), needs a leading magnifier glyph ([search](./search.md)), or opens a sheet-driven option list ([select](./select.md)).

package/agents/components/form-field/textarea.spec.json

@@ -133,14 +133,22 @@
     "hovered": { "overlay": null, "border": "borderHover" },
     "pressed": {
       "border": "borderHover",
-      "overlay": { "color": "text", "opacity": "sys.state.pressed" }
+      "overlay": { "color": "text", "opacity": "sys.state.pressed" },
+      "nestedActionScope": "The pressed overlay (and hover stroke) is suppressed while the pointer presses / hovers the trailing clear button — that '×' is an independent nested action, so the small control owns the state and the large field does not also read as pressed. The visual-state boundary matches the action boundary."
     },
     "active": {
+      "isFocusState": true,
       "overlay": null,
       "border": "borderActive",
       "strokeWeight": "activeStrokeWeight",
       "caret": "visible",
-      "note": "Stroke steps from `hairline` (1px) to `activeStrokeWeight` (2px) as an inset box-shadow — same pixel-stable contract as input."
+      "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": "This IS the field's keyboard/input-focus state — `active` (caret visible, input engaged) and `:focus-visible` coincide for a text field, so there is no separate `focused` state; the focus ring described here (and in the parallel `focusIndicator` block) is the focus affordance. Stroke steps from `hairline` (1px) to `activeStrokeWeight` (2px) as an inset box-shadow — same pixel-stable contract as input."
     },
     "disabled": {
       "overlay": null,

package/agents/components/header/header.md

@@ -1,5 +1,7 @@
 # Header
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/header/header.md`](../../../i18n/ko/schema/components/header/header.md)
+
 The labelled header that names a region and exposes its one highest-priority affordance. Two members share this contract and split on a **tone/weight axis**: **[Main](./main.md)** (`<Header>`) — the louder `onSurface` section heading at 16 / 20 that owns the See-all action, the icon drill-in, and the sort/filter dropdown — and **[Sub](./sub.md)** (`<SubHeader>`) — the quieter muted `onSurfaceVariant` group label at 14 that names the rows beneath it and carries at most a single Text Button action.
 
 **Layout inset.** `full-bleed` — both members have a transparent background and own their `container.md` (16) inline rail, so the label lands on the same rail as the List rows / Feed items it heads with no host help. Drop the header directly above the labelled region as a sibling; do **not** wrap it in a `padding-inline` / `px-*` / `style={{ padding }}` div, and do not pay the rail again on the host. A bundling host (Carousel, DirectoryList, NavList, SideSheet column) stays full-bleed and absorbs only the header's block padding into its stack rhythm. See [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).

package/agents/components/header/main.md

@@ -1,5 +1,7 @@
 # Main
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/header/main.md`](../../../i18n/ko/schema/components/header/main.md)
+
 The louder member of the [Header](./header.md) family — a labelled `onSurface` heading + an optional trailing affordance, reached as `<Header>`. The composable header anatomy reused across [Carousel](../carousel/carousel.md), in-sheet sub-sections, bounded cards, [SideSheet](../side-sheet/side-sheet.md) drawer columns, and any host that needs a leading title + one trailing commit.
 
 **Reach for this when** a labelled block needs an `onSurface` heading and at most one trailing commit (See-all link, drill-in chevron, or sort dropdown). **Skip when** the block needs only a quiet muted group label — that is the family's [Sub](./sub.md) (`<SubHeader>`); when the block has multiple actions; the trailing affordance is a destructive commit; or the surrounding host already owns a heading at the same rung.

package/agents/components/header/sub.md

@@ -1,5 +1,7 @@
 # Sub
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/header/sub.md`](../../../i18n/ko/schema/components/header/sub.md)
+
 Quiet section-dividing label — a 14px (`sys.typo.label.md`, 14 / Semibold) line in the muted `sys.color.onSurfaceVariant` tone that names the group of rows beneath it ("Following", "More Topics to follow"). The muted tone is the dividing device: it reads as a region label rather than a heading that competes with the page title, while the label-weight typo keeps it from dissolving into body copy. Rendered as a semantic `<h3>` by default so screen-reader heading navigation lands on the group label.
 
 It may carry one quiet trailing affordance — a single [Text Button](../button/text.md) `action` ("See all", "Edit", "Manage") — for a region-level commit that stays subordinate to the muted label. Icon drill-in and dropdown disclosure are *not* SubHeader's: those belong on [Main](./main.md), whose louder `onSurface` heading earns the heavier affordance set.

package/agents/components/list/accordion.md

@@ -1,5 +1,7 @@
 # Accordion
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/list/accordion.md`](../../../i18n/ko/schema/components/list/accordion.md)
+
 Expandable-row List sub. Each item exposes a List-row trigger (label + auto-rendered trailing chevron that rotates `180°` on expand) and a body that paints below it when open. Rows tile flush with the family hairline `outlineVariant` divider between them; an extra rule paints between the open trigger and its child row group.
 
 **Reach for this when** a list of titled sections is too long to keep open at once — FAQs, T&C sections, expandable filter groups, settings groups with infrequent edits, hierarchical menus (companies → channels, regions → cities). **Skip when** bodies are short enough to read inline (use [Carousel](../carousel/carousel.md) per group), the user needs to act on labels (use a [List/standard](./standard.md) drill-in row or [List/radio](./radio.md)), or every item should be visible at once (stack [Carousel](../carousel/carousel.md)s).

package/agents/components/list/accordion.spec.json

@@ -158,6 +158,15 @@
     "pressed": {
       "overlay": { "color": "label", "opacity": "sys.state.pressed" }
     },
+    "focused": {
+      "focusRing": {
+        "composition": "inward",
+        "layer": "::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 — a three-layer inward ring inside the trigger's footprint, 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 trigger is in."
+    },
     "disabled": {
       "containerOpacity": "sys.state.disabled",
       "pointerEvents": "none"

package/agents/components/list/entry.md

@@ -1,5 +1,7 @@
 # Entry
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/list/entry.md`](../../../i18n/ko/schema/components/list/entry.md)
+
 Directory-entry [List](./list.md) sub — an entity row pairing an optional leading [Thumbnail](../thumbnail/thumbnail.md) avatar with an identity group (label, optional inline `count` Badge, optional `secondary` line and `description`). Same click semantics as the [Standard sub](./standard.md); geometry, state overlays, and inward focus ring delegate to the [family-wide rules](./list.md). Slots and Anatomy below carry the rung and slot detail.
 
 **Reach for this when** rendering an entity-row directory — follow suggestion, member directory, subscription / channel / topic / playlist directory, mention / recipient picker, entity search result — or, with `thumbnail` omitted, label-only nav rows (settings menu, category index). **Skip when** you need a Feed-specific attribution cluster (use [Metadata](../metadata/metadata.md) for Post / Ad card heads).

package/agents/components/list/entry.spec.json

@@ -194,6 +194,26 @@
         "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 row is in; never via plain mouse click."
+    },
+    "nestedActionScope": "The hover / pressed overlay is suppressed while the pointer sits on the independent trailing action (a favorite / follow / overflow control). The small control owns the state; the large row does NOT also read as hovered / pressed. The visual-state boundary matches the event boundary (the trailing action already stops propagation).",
     "disabled": {
       "containerOpacity": "sys.state.disabled",
       "containerOpacityScope": "Dims the row content only — the inter-row divider and the focus overlay keep full opacity, so a disabled row never fades the hairline rule between it and the next row.",
@@ -224,7 +244,7 @@
     "rowClickTarget": "Whole row is clickable when an `onClick` is bound to the item. The thumbnail is never a separate hit target.",
     "identityGroupFlush": "Label and inline count tile flush on the primary line with `sys.layout.inline.sm` (4) horizontal separation and no vertical gap — they read as one tight identity block.",
     "descriptionSingleLine": "Description always renders on a single line and truncates with ellipsis. The row never grows to fit longer description copy — overflow truncates against the trailing slot if present.",
-    "trailingSlotIndependent": "Clicks inside `trailingIcon` stop propagating before they reach the row's `onClick`. Wire a favorite / follow / overflow action there without it committing the row's primary action."
+    "trailingSlotIndependent": "Clicks inside `trailingIcon` stop propagating before they reach the row's `onClick`. Wire a favorite / follow / overflow action there without it committing the row's primary action. The slot is also visually independent: while the pointer hovers / presses it, the row's own hover / pressed overlay is suppressed so the large row never reads as active alongside the small control."
   },
   "forbidden": [
     "thumbnail rendered as a raw <img> outside the chorus-thumbnail slot wrapper",

package/agents/components/list/list.md

@@ -1,5 +1,7 @@
 # List
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/list/list.md`](../../../i18n/ko/schema/components/list/list.md)
+
 A vertically-stacked sequence of rows for menus, settings panels, picker sheets, inline option groups, directory entries, and expandable hierarchies. Four sub-components share one anatomy and diverge on the leading slot, the selection contract, and the expand contract.
 
 **Reach for this when** the rows are same-kind chrome — settings entries, menu options, single-select picker rows, drill-in navigation, directory rows, expandable section headers. **Skip when** the rows are authored content with author + body + footer (use [Feed](../feed/feed.md)) or a horizontal collection of curated cards (use [Carousel](../carousel/carousel.md)). Pick the sub by the trailing affordance and the leading slot: display / navigation rows → [Standard](./standard.md) (no `thumbnail` for text-only; pass `thumbnail` for the 40px avatar-leading image type, label + optional `supportingText`); single-select radio → [Radio](./radio.md); 32 / 40 / 48 avatar leading with identity-group (label + inline `count`) + optional single-line description → [Entry](./entry.md); drill-in chevron → any [Standard](./standard.md) / [Radio](./radio.md) row with `nav: true`; expand chevron that rotates on click → [Accordion](./accordion.md).
@@ -12,7 +14,7 @@ A vertically-stacked sequence of rows for menus, settings panels, picker sheets,
 - **Row geometry.** 8px block / 16px inline padding (`layout.container.xs` / `layout.container.md`); min-height 48px. Row spacing is **role-based**, not a single flex gap: the **text group → trailing action** gap is a fixed `layout.inline.md` (8px) in every sub, while the **leading → text group** gap depends on the leading *type* — `layout.inline.md` (8px) for an icon leading (Radio's indicator), `layout.inline.lg` (12px) for an image leading (a Standard row's `thumbnail` image type / Entry Thumbnail). A label-only Entry row (no `thumbnail`) drops the leading gap to 0. Row grows when `supportingText` is present.
 - **Label column.** Label: 16px / Regular / `onSurface` (sub-list rows compressed inside an accordion render at 14px / Regular — see [accordion.md](./accordion.md) § Nested list; Entry rows promote the label to 14px / Semibold so the inline `count` reads as part of the identity group). SupportingText: 14px / Regular / `onSurfaceVariant`, sits directly under the label with no extra gap — the two lines stack on the label-column's intrinsic line-box rhythm. The Entry sub replaces the second line with a single-line `description` (12px / Regular / `onSurfaceVariant`, separated from the identity group by `ref.space.25` (2) — see [entry.md](./entry.md)). All secondary lines truncate with ellipsis.
 - **Strong-label opt-in.** Pass `strong={true}` on a row (`<Accordion.Item strong>` on the accordion sub) to promote the label's weight from Regular (`body.*-weight`, 400) to Semibold (`label.*-weight`, 600) at the same size and line-height — `body.md → label.lg` at the 16 rung, `body.sm → label.md` at the 14 rung. The row's geometry (height, dividers, slot positions) is unchanged; only the label glyphs gain stroke weight. Reach for it when one row needs to read as the primary entry within a denser scan — the active company in a directory, the canonical answer in an FAQ, the user's own row in a member list. Use sparingly — a stack where every row is strong reads as the default again, defeating the marker.
-- **States.** `selected` exists only on Radio. The whole row is the interactive surface.
+- **States.** `selected` exists only on Radio. The whole row is the interactive surface — except where a trailing slot carries an *independent action* (a Follow / mute / favorite button, an overflow control). That action is a nested touch target: it stops click / key propagation so it never commits the row, and while the pointer hovers / presses it the row's own hover / pressed overlay is **suppressed** so the large row never reads as active alongside the small control. The decorative `nav: true` chevron is exempt — it is the row's drill-in affordance, so hovering it still lights the whole row.
 - **Focus indicator.** Composition: Inward (see [Focus ring composition](../../DESIGN.md#focus-ring-composition)) — inset shadows entirely inside the row's box. Trigger: `:focus-visible`.
 - **Accessibility.** Every non-Radio sub (Standard / Entry / Accordion) exposes `role="list"`; Radio exposes `role="radiogroup"` with each row `role="radio"` + `aria-checked`. A `nav: true` row's trailing chevron is decorative (`aria-hidden`) — the whole row stays the single interactive target. Keyboard navigation (Arrow ↑/↓, Home/End) is handled by the container; Radio also commits on Space / Enter.
 

package/agents/components/list/radio.md

@@ -1,5 +1,7 @@
 # Radio
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/list/radio.md`](../../../i18n/ko/schema/components/list/radio.md)
+
 Single-select picker List sub-component. Each row carries a leading 24px (`sys.icon.lg`) radio indicator; clicking commits that row's value via `onChange(value)`. Exactly one row is selected at a time. Row geometry, typography, divider, state overlays, and inward focus ring all delegate to the [family-wide rules](./list.md); this sub documents the Radio-specific leading indicator and selection contract.
 
 **Reach for this when** the user picks exactly one value from a short, fully-visible set — sort order, range filter, equity tier. **Skip when** multiple values may be selected (use [`Chip variant="filter"`](../chip/filter.md) or [`Button variant="check"`](../button/check.md)), the set is long enough to demand a sheet-driven picker ([Select](../form-field/select.md)), or the row *only* navigates without selecting (use a [Standard](./standard.md) row with `nav: true`). When a value both selects *and* opens a deeper screen — a major category — keep Radio and add `nav: true` (see [Major category with a second screen](#major-category-with-a-second-screen)).

package/agents/components/list/radio.spec.json

@@ -142,6 +142,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 row is in; never via plain mouse click."
+    },
     "selected": {
       "leading": "Filled primary indicator; row foreground stays at onSurface. No fill change on the row itself."
     },

package/agents/components/list/standard.md

@@ -1,5 +1,7 @@
 # Standard
 
+> 🇰🇷 한국어: [`i18n/ko/schema/components/list/standard.md`](../../../i18n/ko/schema/components/list/standard.md)
+
 The default [List](./list.md) sub — display or navigation rows over the shared List anatomy. The whole row is the click target; there is no selection model. A row is text-only by default, opting into a **leading image** (40px [Thumbnail](../thumbnail/thumbnail.md) via `thumbnail`) or a **leading icon** (`sys.icon.lg` glyph via `icon`). Geometry, typography, divider, state overlays, and inward focus ring delegate to the [family-wide rules](./list.md).
 
 **Layout inset.** `full-bleed` — sits as a direct child of the page shell. Each row pays its own `16px inline / 8px block` padding via `layout.container.*`; do **not** wrap the list in another `padding-inline` / `px-*` / `style={{ padding: … }}` div. Inside a bounded surface (Card / Dialog / BottomSheet / Sheet), apply the negative-margin opt-out — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
@@ -216,6 +218,51 @@ import { List } from '@teamblind-chorus/ui';
 />
 ```
 
+### With an embedded Banner
+
+Pass a `banner` on a row and a [Banner](../banner/banner.md) renders **below** the row's text group, `8px` (`sys.layout.stack.xs`) down, spanning the row's full content width (aligned to the same 16px inline inset as the label above it). The row flips from a single line to a vertical stack — text group on top, Banner underneath. Reach for it when a row needs an in-row call-out tied to *that row's* subject (a follow-up prompt, a capability nudge, a single-line CTA), rather than a separate full-width Banner detached from the row.
+
+The Banner keeps its full prop surface — here `appearance="accent"` + `neutralBody` for the quiet-tint shape, a blue `CheckCircleFillIcon` leading the single-line body, and a `trailingAction` Text Button with a trailing chevron. The Banner is a nested-action region: its button never commits the row, and the row's hover / pressed overlay is suppressed over it. The rows lead with fill-type category glyphs (`BriefcaseFillIcon`, `FlagFillIcon`) that the leading slot tones to `onSurfaceVariant`.
+
+```preview
+list/standard-embedded-banner
+---
+import { Banner, Button, List } from '@teamblind-chorus/ui';
+import { BriefcaseFillIcon, CheckCircleFillIcon, ChevronRightIcon, FlagFillIcon } from '@teamblind-chorus/ui/icons';
+
+<List
+  aria-label="Career"
+  items={[
+    {
+      value: 'major',
+      label: 'My major: Computer Science',
+      strong: true,
+      icon: <BriefcaseFillIcon />,
+      banner: (
+        <Banner
+          appearance="accent"
+          neutralBody
+          icon={<CheckCircleFillIcon size={16} style={{ color: 'var(--sys-color-primary)' }} />}
+          trailingAction={(
+            <Button variant="text" appearance="accent" size="small" trailingIcon={<ChevronRightIcon />}>
+              Expert Q&A
+            </Button>
+          )}
+        >
+          Ask a professional in this field
+        </Banner>
+      ),
+    },
+    {
+      value: 'roadmap',
+      label: 'View career roadmap',
+      icon: <FlagFillIcon />,
+      nav: true,
+    },
+  ]}
+/>
+```
+
 ## Slots
 
 - **container** — outer vertical stack (delegates to family).
@@ -229,6 +276,7 @@ import { List } from '@teamblind-chorus/ui';
 - **trailingIcon** *(optional, per-row)* — consumer-supplied node at the trailing edge. Each row decides independently. Canonical fills: a 16px icon (e.g. an external-link mark), or `<Button variant="text" appearance="accent">` (Follow / Invite) on leading-image rows. A status badge does **not** go here — it tiles next to the label via `count`. Its own hit target: a tap on this slot stops propagating before it reaches the row's `onClick`. Overrides the nav chevron on the same row.
 - **navChevron** *(optional, per-row)* — auto-rendered 16px right-pointing chevron, painted when the row sets `nav: true`. `onSurfaceVariant`, decorative; never a separate hit target.
 - **divider** *(optional, per-row)* — pass `divider: false` to suppress the row's bottom hairline. Use when a visual group ends mid-stack and the divider would visually fence off the next group from its label.
+- **banner** *(optional, per-row)* — an embedded [Banner](../banner/banner.md) below the row's text group, `8px` (`sys.layout.stack.xs`) down, spanning the row's full content width. The row stacks (text group over Banner). A nested-action region: its own controls never commit the row, and the row's hover / pressed overlay is suppressed over it. Canonical fill: `<Banner appearance="accent" neutralBody icon={…} trailingAction={…}>` — an in-row call-out tied to the row's subject.
 
 ## States