@teamblind-chorus/ui 1.1.0 → 1.2.0

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/form-field/input.spec.json

@@ -155,12 +155,19 @@
       "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.spec.json

@@ -96,12 +96,19 @@
       "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.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.spec.json

@@ -137,11 +137,18 @@
       "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/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.spec.json

@@ -194,6 +194,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."
+    },
     "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",

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

@@ -218,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).
@@ -231,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
 

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

@@ -3,7 +3,7 @@
   "name": "List",
   "family": "list",
   "subcomponent": "standard",
-  "description": "The default List variant — display or navigation rows over the shared List anatomy. The whole row is the click target; no selection model. A row is text-only by default (no leading slot); it opts into a **leading image** (the image type) by passing a `thumbnail`, which renders a 40px [Thumbnail](../thumbnail/thumbnail.md) at the leading edge with a 12px (`sys.layout.inline.lg`) gap to the text group, or into a **leading icon** (the icon type) by passing an `icon`, which renders a 24px (`sys.icon.lg`) glyph with an 8px (`sys.layout.inline.md`) gap. A row opts into a trailing drill-in chevron with `nav: true` (the drill-in case — the row routes the user to another surface); a per-item `trailingIcon` overrides the auto chevron. A row opts into an inline **count badge** to the right of the label via `count` — separated from the label by `sys.layout.inline.sm` (4), the unread / status-count case — and it composes with the chevron / trailing slot on the same row. For the richer directory shape (selectable 32/48/56 avatar + stacked `secondary` identity line) reach for [list/entry](./entry.md); Standard's leading image is single-density at the 40 rung.",
+  "description": "The default List variant — display or navigation rows over the shared List anatomy. The whole row is the click target; no selection model. A row is text-only by default (no leading slot); it opts into a **leading image** (the image type) by passing a `thumbnail`, which renders a 40px [Thumbnail](../thumbnail/thumbnail.md) at the leading edge with a 12px (`sys.layout.inline.lg`) gap to the text group, or into a **leading icon** (the icon type) by passing an `icon`, which renders a 24px (`sys.icon.lg`) glyph with an 8px (`sys.layout.inline.md`) gap. A row opts into a trailing drill-in chevron with `nav: true` (the drill-in case — the row routes the user to another surface); a per-item `trailingIcon` overrides the auto chevron. A row opts into an inline **count badge** to the right of the label via `count` — separated from the label by `sys.layout.inline.sm` (4), the unread / status-count case — and it composes with the chevron / trailing slot on the same row. For the richer directory shape (selectable 32/48/56 avatar + stacked `secondary` identity line) reach for [list/entry](./entry.md); Standard's leading image is single-density at the 40 rung. A row opts into an embedded **`banner`** — a [Banner](../banner/banner.md) painted below the row's text group at the row's full content width, `sys.layout.stack.xs` (8) below it — for an in-row call-out tied to that row's subject.",
   "element": "ul",
   "props": {
     "embedded": {
@@ -67,6 +67,13 @@
     "navChevron": {
       "required": false,
       "description": "Auto-rendered 16px right-pointing chevron at the trailing edge, painted when the row sets `nav: true` — the drill-in affordance signalling the row routes to another surface. `onSurfaceVariant` tone, decorative (`aria-hidden`); never a separate hit target — the whole row is the click target. A per-item `trailingIcon` replaces it."
+    },
+    "banner": {
+      "required": false,
+      "description": "Optional embedded [Banner](../banner/banner.md) painted **below** the row's text group, separated by `sys.layout.stack.xs` (8). The row flips from a single horizontal line to a vertical stack — the normal leading + label + trailing line on top, the Banner spanning the row's **full content width** (aligned to the same 16px inline inset as the label above it) underneath. Reach for it when a list 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 own fill / radius / padding and its full prop surface (use `appearance=\"accent\"` + `neutralBody` for the quiet-tint call-out shape, a leading `icon`, a `trailingAction` Text Button). It is a **nested-action region**: clicks inside it stop propagating before they reach the row's `onClick`, and the row's hover / pressed overlay is suppressed while the pointer sits on it — same contract as `trailingIcon`.",
+      "accepts": [
+        "banner"
+      ]
     }
   },
   "rowProps": {
@@ -102,6 +109,11 @@
       "optional": true,
       "description": "Trailing-edge node. Wrapped in a slot that stops click propagation so the slot is its own hit target separate from the row's `onClick`."
     },
+    "banner": {
+      "type": "node",
+      "optional": true,
+      "description": "Embedded `<Banner>` rendered below the row's text group at the row's full content width, `sys.layout.stack.xs` (8) below it. A nested-action region: its own controls (e.g. a `trailingAction` Text Button) never commit the row, and the row's hover / pressed overlay is suppressed over it. Canonical fill: `<Banner appearance=\"accent\" neutralBody icon={…} trailingAction={…}>…</Banner>`."
+    },
     "divider": {
       "type": "boolean",
       "default": true,
@@ -147,6 +159,8 @@
     "leadingIconGapNote": "8px (`sys.layout.inline.md`) between a leading 24px (`sys.icon.lg`) icon (the icon type) and the text group — the icon-leading rung of the family's role-based row spacing (the base leading gap), narrower than the 12px image rung. Applies only to rows that carry an `icon`.",
     "trailingActionGap": "sys.layout.inline.md",
     "trailingActionGapNote": "Fixed 8px (`sys.layout.inline.md`) between the text group and a trailing icon / nav chevron — the family-wide trailing gap, identical across every List variant.",
+    "bannerGap": "sys.layout.stack.xs",
+    "bannerGapNote": "8px (`sys.layout.stack.xs`) vertical gap between the row's text group and an embedded `banner` below it. The Banner spans the row's full content width (the 16px inline inset is the row's own padding, not paid again by the Banner — see banner.md § Layout inset).",
     "labelToCountGap": "sys.layout.inline.sm",
     "labelToCountGapNote": "4px (`sys.layout.inline.sm`) between the label and an inline `count` badge — they tile flush on the primary line as one label+count block, narrower than the 8px trailing gap. Mirrors list/entry's identity-group spacing.",
     "dividerWidth": "sys.borderWidth.hairline",
@@ -179,6 +193,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."
+    },
     "nestedActionScope": "The hover / pressed overlay is suppressed while the pointer sits on an independent trailing action (a `trailingIcon` button — favorite / mute / Follow). The small control owns the state; the large row does NOT also read as hovered / pressed. The decorative nav chevron is exempt — it is the row's own drill-in affordance, so hovering it still lights the whole row. The visual-state boundary matches the event boundary (the trailing action already stops propagation).",
     "disabled": {
       "containerOpacity": "sys.state.disabled",
@@ -217,6 +250,8 @@
     "nav chevron as a separate hit target — the drill-in chevron is decorative; the whole row is the click target",
     "leading thumbnail at a size other than the row's intrinsic 40 rung",
     "compact directory rows (selectable 32/48/56 avatar + stacked secondary line + optional toggle) built as a leading-image Standard row — that directory anatomy is [list/entry](./entry.md); Standard's image type is single-density at the 40 rung. (Standard does carry an inline `count` badge next to the label for unread / status counts, but not the avatar-rung directory shape.)",
-    "raw `border:` on the row — list seam is the family's bottom divider via outlineVariant"
+    "raw `border:` on the row — list seam is the family's bottom divider via outlineVariant",
+    "embedded `banner` painted with a per-child `margin-block` / `padding-block` wrapper to fake the 8px gap — the text-group↔Banner gap is the row stack's `gap: sys.layout.stack.xs`, and the Banner's horizontal inset is the row's own 16px padding; Banner ships no outer margin",
+    "embedded `banner` as a separate `<List>` row beneath the header — the call-out belongs to its row's subject, so it nests inside that row via `item.banner`, not as a sibling row that the divider would fence off"
   ]
 }

package/agents/components/nav-card/nav-card.spec.json

@@ -126,6 +126,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 card'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 card is in."
+    },
     "disabled": {
       "containerOpacity": "sys.state.disabled",
       "pointerEvents": "none"

package/agents/components/page-shell/page-shell.family.json

@@ -17,6 +17,6 @@
   },
   "spec": "page-shell.md",
   "subcomponents": [
-    { "slug": "page-shell", "md": "page-shell.md", "default": true, "specMissing": true }
+    { "slug": "page-shell", "spec": "page-shell.spec.json", "md": "page-shell.md", "default": true }
   ]
 }

package/agents/components/page-shell/page-shell.md

@@ -33,6 +33,39 @@ renders:
 </div>
 ```
 
+## Default
+
+`NavigationBar` pins to the top, `TabBar` pins to the bottom, and only the `<main>` body scrolls. Scroll the list inside the window — the bars stay put while the content moves.
+
+```preview
+page-shell/default
+---
+import { PageShell, NavigationBar, TabBar, List } from '@teamblind-chorus/ui';
+
+<PageShell
+  nav={<NavigationBar variant="main" title={…} />}
+  tabBar={<TabBar value={tab} onChange={setTab} items={items} />}
+>
+  <List items={settings} />
+</PageShell>
+```
+
+### Inline body
+
+When the screen carries inline (non-full-bleed) content, pass `bodyProps` to add the page gutter to `<main>` so the body sits inset from the screen edge while the bars stay pinned.
+
+```preview
+page-shell/inline-body
+---
+<PageShell
+  bodyProps={{ style: { paddingInline: 'var(--sys-layout-page-md)' } }}
+  nav={<NavigationBar variant="sub" title="About" />}
+  tabBar={<TabBar value={tab} onChange={setTab} items={items} />}
+>
+  {/* inline content — honors the page gutter */}
+</PageShell>
+```
+
 ## Props
 
 | prop | type | notes |

package/agents/components/page-shell/page-shell.spec.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "PageShell",
+  "family": "page-shell",
+  "description": "The app scaffold that PINS `NavigationBar` (top) and `TabBar` (bottom) while only the body scrolls. Chorus bars render in flow and do NOT self-pin; PageShell is the pinning mechanism — a full-height (100dvh) flex column whose middle `<main>` is the sole scroll region (`flex: 1 1 auto; min-height: 0; overflow-y: auto; overscroll-behavior: contain`). The `nav` and `tabBar` slots render as flow children at their natural height; without this skeleton the whole page scrolls as one piece and both bars drift off-screen on long content. The shell owns ONLY the pin/scroll mechanics — not a content gutter — so the body honors the normal full-bleed / inline padding contract; pass `bodyProps` to add the page gutter to `<main>` when the screen carries inline (non-full-bleed) content. Never give the bars `position: sticky` / `fixed`: that double-applies their own `env(safe-area-inset-*)`. Single-spec family.",
+  "element": "div",
+  "props": {
+    "nav": {
+      "type": "node",
+      "optional": true,
+      "description": "Rendered in flow at the top — a `NavigationBar`. Pays its own `safe-area-inset-top`; the shell does NOT re-pay it. Pinned by the flex column, never by `position: sticky` / `fixed`."
+    },
+    "tabBar": {
+      "type": "node",
+      "optional": true,
+      "description": "Rendered in flow at the bottom — a `TabBar`. Pays its own `safe-area-inset-bottom`; the shell does NOT re-pay it. Pinned by the flex column, never by `position: sticky` / `fixed`."
+    },
+    "children": {
+      "type": "node",
+      "required": true,
+      "description": "The scrolling body content — the sole scroll region. Rendered inside `<main class=\"chorus-page-shell__body\">`."
+    },
+    "bodyProps": {
+      "type": "object",
+      "optional": true,
+      "description": "Spread onto `<main>` — use to add a page gutter (`style={{ paddingInline: 'var(--sys-layout-page-md)' }}`) when the screen carries inline (non-full-bleed) content. `className` composes with `chorus-page-shell__body`; the rest spread as-is. Do NOT use it to re-pay a bar's safe-area inset."
+    },
+    "className": {
+      "type": "string",
+      "optional": true,
+      "description": "Composes with the shell root's own `chorus-page-shell` class. Use for placement only; never to override the pin/scroll mechanics."
+    }
+  },
+  "slots": {
+    "nav": {
+      "required": false,
+      "description": "Flow child at the top of the column, rendered at its natural height (typically a `NavigationBar`). Stays pinned because only the body scrolls beneath it. Pays its own viewport-top safe-area inset.",
+      "omittedBehavior": "collapse",
+      "accepts": [
+        "navigation-bar"
+      ]
+    },
+    "body": {
+      "required": true,
+      "intrinsic": true,
+      "description": "The `<main>` element — the ONLY scroll region. `flex: 1 1 auto; min-height: 0; overflow-y: auto; overscroll-behavior: contain`. Takes the remaining column height between the bars and scrolls its children; the `min-height: 0` line is load-bearing (without it the flex body refuses to shrink and the page scrolls as one piece). The shell renders this element itself and fills it with `children`.",
+      "omittedBehavior": "error"
+    },
+    "tabBar": {
+      "required": false,
+      "description": "Flow child at the bottom of the column, rendered at its natural height (typically a `TabBar`). Stays pinned because only the body scrolls above it. Pays its own viewport-bottom safe-area inset.",
+      "omittedBehavior": "collapse",
+      "accepts": [
+        "tab-bar"
+      ]
+    }
+  },
+  "sizing": {
+    "shellDisplay": "flex",
+    "shellDirection": "column",
+    "shellHeight": "100dvh",
+    "bodyFlex": "1 1 auto",
+    "bodyMinHeight": "0",
+    "bodyOverflowY": "auto",
+    "bodyOverscrollBehavior": "contain",
+    "bodyGutter": "sys.layout.page.md",
+    "note": "The shell paints no fill of its own — it is a transparent flex column; `nav`, `body`, and `tabBar` each carry their own surface. The dvh / flex / min-height values are fixed layout mechanics, not a size axis. `bodyGutter` (`sys.layout.page.md`) is NOT applied by default — it is the canonical page-rail value the consumer opts into via `bodyProps` when the body carries inline (non-full-bleed) content; full-bleed screens leave the body gutter at 0."
+  },
+  "behavior": {
+    "pinMechanism": "A full-height flex column (`display: flex; flex-direction: column; height: 100dvh`) where `nav` and `tabBar` are flow children at their natural height and `<main>` takes the remaining space as the sole scroll region. The bars stay put on long lists because the body — not the shell or the page — is what scrolls.",
+    "soleScrollRegion": "Only `<main class=\"chorus-page-shell__body\">` scrolls (`overflow-y: auto`). `min-height: 0` lets the body shrink below its content height so it (not the shell) becomes the scroll container; `overscroll-behavior: contain` keeps scroll chaining from leaking to the document.",
+    "barsDoNotSelfPin": "Chorus bars render in flow and pay only their own `env(safe-area-inset-*)`; pinning is the shell's job. Never give `NavigationBar` / `TabBar` `position: sticky` / `fixed` — that double-applies their safe-area insets. A dev-only `usePinnedBarGuard` warns in the console when a bar is rendered inside a scrolling region instead of a shell.",
+    "noContentGutter": "PageShell owns only the pin/scroll mechanics, not a content gutter — the body honors the normal full-bleed / inline padding contract. Pass `bodyProps={{ style: { paddingInline: 'var(--sys-layout-page-md)' } }}` to add the page gutter when the screen carries inline content.",
+    "overlayNavExempt": "The overlay `NavigationBar` (floating over a `ProfileHeader` cover) is the exception — it scrolls with the hero by design and is NOT pinned by the shell; place it inside the body, not the `nav` slot."
+  },
+  "forbidden": [
+    "NavigationBar / TabBar given position: sticky / fixed inside the shell — the flex column is the pin; sticky/fixed double-applies the bar's safe-area inset",
+    "a bar rendered inside the scrolling body (nav/tabBar passed as children) instead of the nav / tabBar slot — it scrolls away with the content on long lists",
+    "hand-rolling the flex-column recipe instead of using PageShell — the min-height:0 / overflow-y:auto / overscroll-behavior:contain mechanics ship in the component, not a copy-paste CSS recipe",
+    "omitting min-height:0 on the body (or overriding it) — without it the flex body refuses to shrink and the whole page scrolls as one piece, drifting the bars off-screen",
+    "wrapping the shell in another scroll container or giving the shell root overflow:auto — the body is the sole scroll region; a second scroller breaks the pin",
+    "re-paying a bar's safe-area inset via bodyProps padding-top / padding-bottom — each bar owns its own viewport inset; the shell and body never re-pay it",
+    "adding a default content gutter to the shell — PageShell owns no gutter; inline padding is opted into per-screen via bodyProps, never baked into the shell"
+  ]
+}

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
+    }
+  ]
+}