@teamblind-chorus/ui 1.0.0

package/agents/components/navigation-bar/search.md

@@ -0,0 +1,96 @@
+# Search
+
+The search top bar — anchored to a dedicated search page reached from a [Main](./main.md) or [Sub](./sub.md) bar's search trigger. Owns the entire search affordance: leading back-arrow Icon Button, single bare-text input filling the row, conditional trailing clear (*×*). Drops the centred title — the input *is* the focus.
+
+**Reach for this when** the entire screen exists to capture a query and show results. **Skip when** search is one affordance among several on a tab root (use [Main](./main.md) with a search trailing action) or when the field lives in-line with content (use the [search](../form-field/search.md) form-field).
+
+**Layout inset.** `full-bleed` — direct child of the page shell. The bar pays its own `16px inline` padding via `layout.container.*`; do **not** wrap it in another `padding-inline` / `px-*` / `style={{ padding: … }}` div. Inside a bounded surface, apply the negative-margin opt-out — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+At rest with an empty field. Placeholder paints in `outline`; the clear (*×*) stays hidden until a value lands.
+
+```preview
+navigation-bar/search/default
+---
+import { NavigationBar } from '@teamblind-chorus/ui';
+
+<NavigationBar variant="search" placeholder="Search by keyword" onBack={() => {}} />
+```
+
+## Use cases
+
+### With value (clear visible)
+
+A non-empty value swaps placeholder for `onSurface` text and reveals the trailing clear (*×*) at the medium 32 × 32 capsule — smaller than the leading back-arrow so it never out-shouts the input. Clicking clear wipes the value, returns focus, and the trailing column collapses; the input's leading edge stays pixel-stable.
+
+```preview
+navigation-bar/search/with-value
+---
+import { NavigationBar } from '@teamblind-chorus/ui';
+
+<NavigationBar
+  variant="search"
+  placeholder="Search by keyword"
+  defaultValue="lighting"
+  onBack={() => {}}
+/>
+```
+
+## Slots
+
+- **leading** *(required)* — 24px back-arrow as the canonical [Icon Button](../button/icon.md) capsule (40 × 40 transparent, 24px glyph).
+- **input** *(required)* — single-line *bare* text input filling the leftover middle column. Bare means no border, no background, no inset stroke — not a [Search](../form-field/search.md) field. Value in `sys.color.onSurface`, placeholder in `sys.color.outline` (`typo.body.md`, 16/Regular). Caret follows the [system caret rule](../../DESIGN.md#caret).
+- **trailing** *(conditional)* — clear (*×*) [Icon Button](../button/icon.md) hosting `XCircleFillIcon`. Always Icon Button's `medium` size (32 × 32 capsule, 16px glyph) so it never over-claims weight against the bare input. Rendered only when value is non-empty; wipes value and returns focus.
+
+## Anatomy
+
+Three-column grid (leading / input / trailing) — side columns size to content, input column takes `minmax(0, 1fr)`. When the trailing column collapses, the input column expands; the field never reflows its leading edge.
+
+| Slot                  | Container                                                                               | Color                                                                          |
+|-----------------------|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
+| **Bar container**     | `sys.color.surface` fill, 8px block / 16px inline padding, no shadow at rest, **1px bottom divider in `sys.color.outlineVariant`** painted as inset `box-shadow`. | —                                                                              |
+| **Leading**           | Transparent Icon Button capsule (8 padding around 24px glyph).                           | `sys.color.onSurface`                                                          |
+| **Input**             | Bare text — no border, no background, no inset stroke.                                   | Value: `sys.color.onSurface`. Placeholder: `sys.color.outline`. Caret: `sys.color.primary`. |
+| **Trailing (clear)**  | Transparent Icon Button **medium** capsule (32 × 32, 16px glyph).                        | `sys.color.onSurface`                                                          |
+
+The 1px bottom divider (unique to Search) keeps the bare input from bleeding into the results list below; painted as inset `box-shadow` so it never participates in layout.
+
+## Sizes
+
+A single fixed rung. Same geometry as Page.
+
+| Property                          | Value                | Token                              |
+|-----------------------------------|----------------------|-------------------------------------|
+| Container padding (block × inline)| 8 × 16               | `sys.layout.container.xs` × `sys.layout.container.md` |
+| Min-height                        | 56px                 | raw                                |
+| Slot gap (between slots)          | 16px                 | `sys.layout.inline.xl`             |
+| Icon-capsule padding              | 8px                  | `sys.layout.container.xs`          |
+| Input text                        | 16 / Regular         | `sys.typo.body.md`                 |
+| Leading icon                      | 24px                 | `sys.icon.lg`                      |
+| Trailing (clear) icon             | 16px (32 × 32 capsule)| `sys.icon.md` ‡                   |
+
+‡ Clear button uses Icon Button's `medium` size, not `xlarge` — clear is a secondary affordance to typing.
+
+## States
+
+The bar has no interactive state of its own. Leading and trailing inherit [Icon Button](../button/icon.md)'s recipe. The input follows the bare-text-field shape — only the caret and placeholder ↔ value colour swap signal interaction; no overlay because the field has no chrome to tint.
+
+| State      | Overlay opacity            | Additional                                                                 |
+|------------|----------------------------|-----------------------------------------------------------------------------|
+| `default`  | —                          | Caret hidden. Empty → placeholder in `outline`; value → `onSurface`.        |
+
+**No `disabled` state.** The only screen this bar ever lives on is the search results page itself; gating it there reduces the surface to a dead chrome strip with no escape beyond the back-arrow. If search must be gated (offline, throttled, paused indexing), gate the *trigger* on the prior screen instead.
+
+## Focus indicator
+
+Caret paints per the [system caret rule](../../DESIGN.md#caret). Field has no focus-ring of its own — the bar *is* the page's focus; browser's default focus stays as accessibility floor. Trigger: `:focus-visible`.
+
+## Behavior
+
+- **Submit on Enter.** Fires `onSubmit(value)`; wrapping `<form>` submits.
+- **Clear visibility.** Clear button in DOM only when value is non-empty. Click sets value to `''`, returns focus, fires `onChange('')`.
+- **Escape key.** Clears non-empty value before firing `onBack` on empty — matches platform convention.
+- **Back affordance.** Leading back-arrow fires `onBack`. Host owns routing.
+- **Auto-focus.** `autoFocus` defaults to `true` — set `false` for hydrated queries the user is reviewing.
+- **IME.** Handles composition normally — `onChange` on every keystroke; `onSubmit` only on real Enter (not IME-confirm Enter).

package/agents/components/navigation-bar/search.spec.json

@@ -0,0 +1,142 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "NavigationBar",
+  "family": "navigation-bar",
+  "subcomponent": "search",
+  "description": "Search top bar — anchored to a dedicated search page reached from a Home or Page bar's search trigger. The bar owns the entire search affordance: a leading back-arrow, a single bare-text input that fills the row, and a trailing clear (×) button that wipes the value. Drops the centred title slot Page uses — the input *is* the focus of the screen, and a separate title would compete with the placeholder for the same row. Same 56 min-height and 8 (block) / 16 (inline) padding as Home / Page, so the bar stays at one geometry across a navigation flow (Home → Search → results).",
+  "element": "header",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "search"
+    },
+    "value": {
+      "type": "string",
+      "optional": true,
+      "description": "Controlled value. Omit (and pass `defaultValue` instead) for an uncontrolled field."
+    },
+    "defaultValue": {
+      "type": "string",
+      "optional": true
+    },
+    "placeholder": {
+      "type": "string",
+      "default": "Search by keyword",
+      "description": "Faint guide text shown when the value is empty. Sentence case, typically a one-line invitation (`Search by keyword`, `Search channels`)."
+    },
+    "onChange": {
+      "type": "function",
+      "optional": true,
+      "description": "Called on every keystroke with the new value. Host owns the typeahead / submit pipeline."
+    },
+    "onSubmit": {
+      "type": "function",
+      "optional": true,
+      "description": "Called when the user commits the query (Enter / form submit). Host wires the route or query side-effect."
+    },
+    "onBack": {
+      "type": "function",
+      "required": true,
+      "description": "Wires the leading back-arrow to the host's back action — the bar does not own routing."
+    },
+    "backLabel": {
+      "type": "string",
+      "default": "Back",
+      "description": "aria-label for the leading back-arrow icon button."
+    },
+    "clearLabel": {
+      "type": "string",
+      "default": "Clear search",
+      "description": "aria-label for the trailing clear (×) button."
+    },
+    "autoFocus": {
+      "type": "boolean",
+      "default": true,
+      "description": "Defaults to true because the bar is the search page's primary surface — the user arrived here to type. Set to false when the field receives a hydrated query that the user is reviewing rather than editing."
+    }
+  },
+  "slots": {
+    "leading": {
+      "required": true,
+      "description": "Back-arrow Icon Button (24px glyph in a 40 × 40 transparent capsule). Same anatomy as Page's leading slot — see [navigation-bar.md § Cross-sub contract](./navigation-bar.md#cross-sub-contract). Required because the search bar is always reached from another bar; there is no non-dismissible search screen.",
+      "accepts": [
+        "button"
+      ]
+    },
+    "input": {
+      "required": true,
+      "description": "Single-line bare text input that fills the leftover middle column. Bare = no `border`, no `background`, no inset stroke — it is *not* a [Search bar](../form-field/search.md) field. Renders the value in `sys.color.onSurface` when present; renders the placeholder in `sys.color.outline` when empty. `body.md` (16/Regular). The bar carries the visible search affordance via the placeholder and the page context; the field itself has no chrome of its own.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "trailing": {
+      "required": false,
+      "description": "Clear (×) Icon Button hosting `XCircleFillIcon`. **Always uses Icon Button's `medium` size (32 × 32 capsule, 16px / `sys.icon.md` glyph)** — not the 40 × 40 / 24-glyph `large` size the leading back arrow uses. The clear is a secondary affordance (the user's primary act on this bar is typing); the smaller capsule keeps the clear from over-claiming weight against the bare input next to it. Rendered only when the value is non-empty — wipes the value, keeps focus on the input, and disappears the moment the value goes back to empty. Differs from [Search bar](../form-field/search.md)'s clear which gates on focus too: this bar's host page is the search context, so a non-empty value is enough — there is no blurred state to hide it for.",
+      "accepts": [
+        "button"
+      ]
+    }
+  },
+  "sizing": {
+    "containerPaddingBlock": "sys.layout.container.xs",
+    "containerPaddingBlockTop": "calc(env(safe-area-inset-top, 0px) + sys.layout.container.xs)",
+    "containerPaddingInline": "sys.layout.container.md",
+    "minHeight": "56px",
+    "viewportSafeArea": "Bar's block-top padding stacks env(safe-area-inset-top) on top of container.xs so the surface fill extends through the device status-bar / notch zone — scrolled body content does not bleed through the transparent system chrome. Bar is the owner of the viewport-top inset; page shell MUST NOT re-pay it via its own padding-top.",
+    "slotGap": "sys.layout.inline.xl",
+    "iconCapsulePadding": "sys.layout.container.xs",
+    "inputTypo": "sys.typo.body.md",
+    "leadingIconSize": "sys.icon.lg",
+    "trailingIconSize": "sys.icon.md"
+  },
+  "appearance": {
+    "containerFill": "sys.color.surface",
+    "containerBottomDivider": "sys.color.outlineVariant",
+    "leadingColor": "sys.color.onSurface",
+    "inputText": "sys.color.onSurface",
+    "inputPlaceholder": "sys.color.outline",
+    "inputCaret": "sys.color.onSurface",
+    "trailingColor": "sys.color.onSurface"
+  },
+  "layout": {
+    "grid": "Three-column grid: leading / input / trailing. Side columns size to content (auto); the input column takes the leftover space (`minmax(0, 1fr)`). Same shape as Page's grid — only the centre slot's contents differ (a bare input instead of a centred title). When the trailing column collapses (value empty → clear hidden), the input column expands to consume the freed space; the field never reflows its leading edge.",
+    "noTitleSlot": "There is no separate title slot; the input fills the role the Page bar would give the title. Adding a title above or beside the input would compete with the placeholder for the search affordance and break the bar's 56 footprint."
+  },
+  "states": {
+    "note": "The bar carries no interactive state of its own. The leading and trailing slots inherit Icon Button's recipe (default / hovered / pressed / focused — overlays + three-layer focus ring). The Search bar deliberately omits a `disabled` state: the only screen a `navigation-bar/search` ever lives on is the search results page itself, and a non-typable search bar on that page reduces the surface to a dead chrome strip with no escape affordance beyond the back-arrow. If search must be gated (offline / throttled / paused indexing), gate the *trigger* on the prior screen instead and never route into this bar. The input slot follows the bare-text-field shape — no border, no fill, no rest-vs-active stroke; only the caret and the placeholder→value colour swap signal interaction. See `inputStates` for the input-only details.",
+    "inputStates": {
+      "default": {
+        "caret": "hidden",
+        "value": "outline placeholder when empty, onSurface text when present"
+      },
+      "focused": {
+        "caret": "onSurface, per [DESIGN.md → Caret](../../DESIGN.md#caret) — same ink as the value text. The system rule binds caret colour only; intended 2px / 0.75× / rounded-ends geometry is design intent, browser-painted.",
+        "ring": "Field has no focus-ring of its own — the bar is the page's focus. Browsers will still paint their default focus indicator if the user tabs into the input from outside; we keep that as the accessibility floor and do not suppress it.",
+        "note": "Default state on this bar — `autoFocus` defaults to true so the user arrives in the focused state."
+      }
+    }
+  },
+  "focusIndicator": {
+    "description": "The bar itself isn't a focus target. Leading back-arrow and trailing clear inherit Icon Button's outward focus composition; the bare input renders no ring of its own and falls through to the browser's default focus indicator (the platform accessibility floor). See [Icon Button → Focus indicator](../button/icon.md#focus-indicator).",
+    "composition": "delegated",
+    "delegatesTo": "../button/icon.spec.json#/focusIndicator",
+    "inputNote": "The bare input has no field-level ring; browser default focus indicator is intentionally not suppressed so keyboard users still see arrival.",
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "behavior": {
+    "submitOnEnter": "Pressing Enter inside the input fires `onSubmit(value)` (and the surrounding `<form>` submits if one wraps the bar). Host wires the route or the typeahead commit.",
+    "clearVisibility": "The clear button is in the DOM only when the value is non-empty. Clicking clear sets the value to '', returns focus to the input, and fires `onChange('')`.",
+    "escapeKey": "Pressing Escape inside the input clears the value (when non-empty) before firing `onBack` (when already empty) — matches the platform convention that Esc 'undoes' the current input before dismissing the surface.",
+    "backAffordance": "Leading back-arrow fires `onBack`. The bar does not own routing — host wires the navigation. The keyboard equivalent is Esc on an empty value.",
+    "noTitle": "The bar deliberately omits a title. The search context is established by the page the user arrived on (a search route reached from a search trigger), and the placeholder names the field's intent. A separate title would compete for the same row.",
+    "ime": "Input handles IME composition normally — `onChange` fires on every keystroke including composition events; `onSubmit` fires only on a real Enter (not on the IME-confirm Enter that closes a composition)."
+  },
+  "forbidden": [
+    "title bar height different from 56px",
+    "second top bar stacked above it — the search variant already owns the back affordance, no page bar above",
+    "input rendered outside the embedded slot — the input fills the bar, not a separate region",
+    "brand color on the input chrome",
+    "`disabled` prop on the Search variant — gating belongs on the trigger that routes to this bar, not on the bar itself"
+  ]
+}

package/agents/components/navigation-bar/sub.md

@@ -0,0 +1,174 @@
+# Sub
+
+The drill-in top bar — anchored to every screen one step inside a flow. Centred page name, flanked by two independent side slots — each optionally a [Text Button](../button/text.md), an [Icon Button](../button/icon.md), or a [Toolbar Button](../button/toolbar.md) / text link, chosen per side. The title itself is optional too: omit it when the side actions say everything (composer bars). Title drops from Main's `typo.heading.lg` to `typo.heading.sm` (16/Semibold).
+
+**Reach for this when** the screen is one step inside a flow and needs a back affordance plus a single primary action. **Skip when** you're on a tab root (use [Main](./main.md)) or a dedicated search page (use [Search](./search.md)).
+
+**Layout inset.** `full-bleed` — direct child of the page shell. The bar pays its own `16px inline / 8px block` padding via `layout.container.*`; do **not** wrap it 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).
+
+## Default
+
+Back-arrow leading and a *primary*-toned "Save" [Toolbar Button](../button/toolbar.md) trailing.
+
+```preview
+navigation-bar/sub/default
+---
+import { NavigationBar, Button } from '@teamblind-chorus/ui';
+
+<NavigationBar
+  variant="sub"
+  title="Edit profile"
+  leading={{ icon: <ChevronLeftIcon />, 'aria-label': 'Back' }}
+  trailing={<Button variant="toolbar" appearance="accent">Save</Button>}
+/>
+```
+
+## Use cases
+
+### With icon trailing
+
+The trailing slot carries a single icon.
+
+```preview
+navigation-bar/sub/icon-trailing
+---
+import { NavigationBar } from '@teamblind-chorus/ui';
+
+<NavigationBar
+  variant="sub"
+  title="Thread"
+  leading={{ icon: <ChevronLeftIcon />, 'aria-label': 'Back' }}
+  trailing={{ icon: <EllipsisHorizontalIcon />, 'aria-label': 'More' }}
+/>
+```
+
+### With text button trailing
+
+The trailing slot carries a [Text Button](../button/text.md) — *Skip* or *Done*. Reads as inline 16/Semibold `primary` type at rest.
+
+```preview
+navigation-bar/sub/link-trailing
+---
+import { NavigationBar } from '@teamblind-chorus/ui';
+
+<NavigationBar
+  variant="sub"
+  title="Pick your interests"
+  leading={{ icon: <ChevronLeftIcon />, 'aria-label': 'Back' }}
+  trailing={{ label: 'Skip', href: '#skip' }}
+/>
+```
+
+### Text button pair (composer)
+
+Modal composer bars carry a [Text Button](../button/text.md) on **both** sides — leading `default` appearance for the dismissing *Cancel*, trailing `accent` for the committing *Post* — and **omit the page title**: the pair says everything, and the centre cell keeps a non-heading placeholder so both buttons hold their edge columns. The accent side is the single CTA of the bar; never paint both sides accent, and never swap the sides (commit always trails).
+
+```preview
+navigation-bar/sub/text-button-pair
+---
+import { Button, NavigationBar } from '@teamblind-chorus/ui';
+
+<NavigationBar
+  variant="sub"
+  leading={<Button variant="text">Cancel</Button>}
+  trailing={<Button variant="text" appearance="accent">Post</Button>}
+/>
+```
+
+### External page (close-only)
+
+External content visited in-app (embedded webview, in-app browser). Leading drops — no flow to step back; trailing is a single close (×) [Icon Button](../button/icon.md).
+
+```preview
+navigation-bar/sub/external-page
+---
+import { NavigationBar } from '@teamblind-chorus/ui';
+
+<NavigationBar
+  variant="sub"
+  title="Help center"
+  trailing={{ icon: <XIcon />, 'aria-label': 'Close' }}
+/>
+```
+
+### Title only
+
+Both side slots empty — for non-dismissible sub-pages (forced confirmation, terms gate).
+
+```preview
+navigation-bar/sub/title-only
+---
+import { NavigationBar } from '@teamblind-chorus/ui';
+
+<NavigationBar
+  variant="sub"
+  title="Terms of service"
+/>
+```
+
+### Overlay (on hero / cover image)
+
+`appearance="overlay"` paints a transparent container with fixed-white icons and title — the bar floats over a hero / cover image (canonical host: [Profile header](../profile-header/profile-header.md)). The image beneath provides contrast; theme tokens don't apply. The bar still pays its own `env(safe-area-inset-top)` so the status-bar zone reads cleanly. Staged here via [ProfileHeader](../profile-header/profile-header.md) so the preview matches a real-world consumer.
+
+```preview
+navigation-bar/sub/overlay
+---
+import { ProfileHeader } from '@teamblind-chorus/ui';
+
+<ProfileHeader
+  name="General Topic"
+  avatar={{ src: '/avatar.png', alt: 'General Topic' }}
+  cover={{ src: '/cover.jpg', alt: 'Forest skyline at dusk' }}
+  visibility="public"
+  followers="999 followers"
+/>
+```
+
+## Slots
+
+- **leading** *(optional)* — typically a 24px back-arrow (transparent icon capsule), but a [Text Button](../button/text.md) is an equally first-class fill (*Cancel* on composer bars). Chosen independently of the trailing slot.
+- **title** *(optional)* — page's name. Single line, `typo.heading.sm` (16/Semibold) `onSurface`, centred; ellipsis on narrow. Omit it for bars whose side actions carry the meaning (canonical: the composer pair) — the centre cell keeps a non-heading placeholder so the side slots hold their columns.
+- **trailing** *(optional)* — exactly one affordance, chosen independently of the leading slot. Either a single 24px icon (transparent capsule — prefer the object form `trailing={{ icon, 'aria-label' }}` so the 24px Icon Button is auto-rendered; a raw `<Button variant="icon" />` must carry `size="large"`), a [Toolbar Button](../button/toolbar.md) with a label (*Save*, *Done*, *Edit*), or a [Text Button](../button/text.md) sized at `typo.heading.sm`.
+
+## Anatomy
+
+| Slot                  | Container          | Color                                   |
+|-----------------------|--------------------|------------------------------------------|
+| **Bar container**     | `sys.color.surface` fill, 8px block / 16px inline padding, no border, no shadow at rest. | — |
+| **Leading**           | Transparent icon capsule (8 padding around 24px glyph). | `sys.color.onSurface` |
+| **Title**             | Plain text, centred horizontally — not interactive. | `sys.color.onSurface` |
+| **Trailing**          | Transparent icon capsule, [Toolbar Button](../button/toolbar.md), or [Text Button](../button/text.md). | `sys.color.onSurface` (icon / Toolbar) or `sys.color.primary` (Text Button) |
+
+## Sizes
+
+A single fixed rung.
+
+| Property                          | Value                | Token                              |
+|-----------------------------------|----------------------|-------------------------------------|
+| Container padding (block × inline)| 8 × 16               | `sys.layout.container.xs` × `sys.layout.container.md` |
+| Min-height                        | 56px                 | raw — matches Main ‡               |
+| Slot gap (between slots)          | 16px                 | `sys.layout.inline.xl`             |
+| Icon-capsule padding              | 8px                  | `sys.layout.container.xs`          |
+| Title                             | 16 / Semibold        | `sys.typo.heading.sm`              |
+| Leading icon                      | 24px                 | `sys.icon.lg`                      |
+| Trailing icon                     | 24px                 | `sys.icon.lg`                      |
+
+‡ Same 56 footprint as Main — keeps bar height constant across a flow. Natural height 8 + 40 + 8 = 56.
+
+## Layout
+
+Three-column grid (leading / title / trailing) sized **`1fr auto 1fr`** — equal side regions, so the centre `auto` column sits at the bar's geometric horizontal centre regardless of side-slot widths. The trailing column collapses to zero when empty.
+
+## States
+
+The bar has no interactive state. Side slots inherit the recipe of whichever control they host — [Icon Button](../button/icon.md), [Toolbar Button](../button/toolbar.md), or [Text Button](../button/text.md). Title carries no states.
+
+## Focus indicator
+
+Bar isn't a focus target; side slots inherit each control's own focus composition. Trigger: `:focus-visible`.
+
+## Behavior
+
+- **Title centring.** `1fr auto 1fr` pins the title to the geometric centre — neither side slot can push it off-axis.
+- **Title truncation.** Long names truncate with ellipsis; bar never grows past 56px. Safety net only.
+- **Back affordance.** Leading slot is conventionally back-arrow; host wires `onClick` to the framework's back action.

package/agents/components/navigation-bar/sub.spec.json

@@ -0,0 +1,123 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "NavigationBar",
+  "family": "navigation-bar",
+  "subcomponent": "sub",
+  "description": "Drill-in top bar — anchored to every screen one step inside a flow rather than a tab root. The page name sits centred so the title reads as the focus of the screen; a leading slot (typically a back-arrow icon) sits at the row's left edge, and a trailing slot (an Icon Button, a Toolbar Button, or a Text Button) sits at the row's right edge. Title type drops from Main's heading.lg to heading.sm (16/Semibold) so the bar reads as page chrome at one density with the body beneath.",
+  "element": "header",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "sub"
+    },
+    "appearance": {
+      "type": "literal",
+      "values": [
+        "surface",
+        "overlay"
+      ],
+      "default": "surface",
+      "description": "Container fill and foreground tone. `surface` (default) — opaque `sys.color.surface` fill, `onSurface` icons and title; the canonical page-chrome treatment. `overlay` — transparent container with **fixed white** icons (`ref.palette.white.1000`), used when the bar floats over a hero/cover image (e.g. inside [Profile header](../profile-header/profile-header.md)). In `overlay`, the title slot is intentionally muted — pass `title=\"\"` (empty string) when the host already carries page identity below the bar."
+    },
+    "title": {
+      "type": "string",
+      "optional": true,
+      "description": "Page name. Optional — omit it for bars whose side actions say everything (canonical: the composer text-button pair, Cancel / Post). A title-less bar renders a non-heading placeholder in the centre cell so the side slots stay in their 1fr/auto/1fr columns. Pass an empty string in `overlay` appearance when the host (e.g. ProfileHeader) carries the identity directly below the bar."
+    },
+    "leading": {
+      "type": "object",
+      "optional": true,
+      "description": "Optional leading affordance. Accepts the { icon, 'aria-label' } descriptor (renders the 24px Icon Button internally — typically a back-arrow), a { label, href } link descriptor, or a node. Text Button and Icon Button are both first-class fills: pick per side independently of the trailing slot — e.g. a default-appearance Text Button (Cancel) on composer bars."
+    },
+    "trailing": {
+      "type": "node",
+      "optional": true,
+      "description": "Optional trailing affordance — Icon Button / Toolbar Button / Text Button, chosen independently of the leading slot. **Prefer the object form `{ icon, 'aria-label' }` for the icon case** — the component then renders the 24px Icon Button internally and the `sys.icon.lg` contract is guaranteed. If a raw `<Button variant=\"icon\" />` node is passed instead, it MUST carry `size=\"large\"` (= `sys.icon.lg` / 24); `size=\"medium\"` resolves to `sys.icon.md` (16) and breaks symmetry with the leading slot."
+    }
+  },
+  "slots": {
+    "leading": {
+      "required": false,
+      "description": "Typically a 24px back-arrow icon at the start of the row, rendered as a transparent icon capsule. Optional.",
+      "accepts": [
+        "icon",
+        "button"
+      ]
+    },
+    "title": {
+      "required": true,
+      "description": "Page name. Single line, heading.sm / Semibold / onSurface, centred horizontally. Truncates with ellipsis.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "trailing": {
+      "required": false,
+      "description": "Exactly one affordance — Icon Button (24px icon), Toolbar Button (with label), or Text Button (primary 16/Semibold inline).",
+      "accepts": [
+        "icon",
+        "button"
+      ]
+    }
+  },
+  "sizing": {
+    "containerPaddingBlock": "sys.layout.container.xs",
+    "containerPaddingBlockTop": "calc(env(safe-area-inset-top, 0px) + sys.layout.container.xs)",
+    "containerPaddingInline": "sys.layout.container.md",
+    "minHeight": "56px",
+    "viewportSafeArea": "Bar's block-top padding stacks env(safe-area-inset-top) on top of container.xs so the surface fill extends through the device status-bar / notch zone — scrolled body content does not bleed through the transparent system chrome. Bar is the owner of the viewport-top inset; page shell MUST NOT re-pay it via its own padding-top.",
+    "slotGap": "sys.layout.inline.xl",
+    "iconCapsulePadding": "sys.layout.container.xs",
+    "titleTypo": "sys.typo.heading.sm",
+    "leadingIconSize": "sys.icon.lg",
+    "trailingIconSize": "sys.icon.lg"
+  },
+  "appearances": {
+    "surface": {
+      "containerFill": "sys.color.surface",
+      "leadingColor": "sys.color.onSurface",
+      "titleColor": "sys.color.onSurface",
+      "trailingColor": "sys.color.onSurface",
+      "trailingTextButtonColor": "sys.color.primary",
+      "default": true,
+      "note": "Canonical page chrome — opaque surface fill with onSurface foreground."
+    },
+    "overlay": {
+      "containerFill": "transparent",
+      "leadingColor": "ref.palette.white.1000",
+      "titleColor": "ref.palette.white.1000",
+      "trailingColor": "ref.palette.white.1000",
+      "trailingTextButtonColor": "ref.palette.white.1000",
+      "note": "Floats over a hero / cover image (e.g. inside [Profile header](../profile-header/profile-header.md)). Container is transparent; icons paint a fixed white tone regardless of theme — the image beneath provides the contrast, not the active surface tier. The bar still pays its own `env(safe-area-inset-top)` so the status bar zone reads cleanly against the image."
+    }
+  },
+  "layout": {
+    "grid": "Three-column grid: leading / title / trailing, sized `1fr auto 1fr`. The two side columns are equal-width regions (each gets half the leftover space) so the centre `auto` column always sits at the bar's geometric horizontal centre regardless of how wide each side slot's content actually is.",
+    "titleCentring": "Title is anchored to the bar's geometric horizontal centre — measured against the page component container, not against the side slots. A 40px back arrow paired with a 80px primary Toolbar Button still leaves the title perfectly centred; the side slots anchor at the start / end of their respective halves and never displace the title. The action always stays intact; title truncation (ellipsis) kicks in if the natural width exceeds what the bar can give it."
+  },
+  "states": {
+    "note": "Bar itself has no interactive state. Side slots inherit the state recipe of whichever control they host (Icon Button / Toolbar Button / Text Button) — default / hovered / pressed / disabled / focused via the standard overlays + three-layer focus ring. Title carries no states."
+  },
+  "focusIndicator": {
+    "description": "The bar itself isn't a focus target. Its action slots inherit each control's own focus composition — Icon Button → Outward, Toolbar Button → Outward, Text Button → Outward — so the ring belongs to whichever control the keyboard lands on. See the contained sub-components for the visual contract.",
+    "composition": "delegated",
+    "delegatesTo": [
+      "../button/icon.spec.json#/focusIndicator",
+      "../button/toolbar.spec.json#/focusIndicator",
+      "../button/text.spec.json#/focusIndicator"
+    ],
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "behavior": {
+    "titleCentring": "Title is anchored to the bar's geometric horizontal centre via a `1fr auto 1fr` grid (equal-width side regions). Side slots anchor at the start / end of their respective halves and cannot push the title off-centre — even when the leading and trailing controls are very different widths.",
+    "titleTruncates": "Long page names truncate with ellipsis; the bar never grows past 56px. Treat as a safety net — author concise titles.",
+    "backAffordance": "Leading slot is conventionally the back-arrow icon, but the component does not own back routing — host wires onClick or wraps an <a href>."
+  },
+  "forbidden": [
+    "leading action different from back chevron — the sub variant always opens with the back affordance",
+    "title not center-aligned — Sub bar title is centered, never left-aligned",
+    "title bar height different from 56px",
+    "brand color on the title",
+    "raw <Button variant=\"icon\" size=\"medium\" /> in the trailing slot — medium resolves to sys.icon.md (16) and breaks symmetry with the leading 24px back-arrow. Use the object form `trailing={{ icon, 'aria-label' }}` or pass `size=\"large\"` explicitly."
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "page-shell",
+  "name": "PageShell",
+  "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). Without this skeleton the whole page scrolls as one piece and both bars drift off-screen on long content. The `min-height:0` line is load-bearing — omit it and the flex body refuses to shrink. NEVER give the bars position:sticky/fixed: that double-applies their safe-area insets. Replaces the hand-rolled flex-column recipe that was previously prose-only. Single-spec family.",
+  "useCases": [
+    "app screen scaffold with a pinned top NavigationBar and bottom TabBar",
+    "any screen whose long scrolling body must not push the bars off-screen",
+    "the canonical page-shell skeleton (was a copy-paste CSS recipe)"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "full-bleed",
+  "wrapperGuidance": "PageShell IS the top-level shell — render it as the screen root (or directly inside the route / viewport host). It owns ONLY the pin/scroll mechanics, not a content gutter, so the body honors the normal full-bleed / inline padding contract. Pass `nav` and `tabBar` (rendered in flow at top / bottom) and the scrolling content as children; pass `bodyProps` to add a page gutter to <main> when the screen carries inline (non-full-bleed) content.",
+  "usage": {
+    "note": "Compose the bars INTO the shell — do NOT hand-roll a flex column, and do NOT add position:sticky/fixed to the bars (that double-applies their safe-area insets). The dev-only usePinnedBarGuard warns when a bar is rendered inside a scrolling region instead.",
+    "example": "<PageShell nav={<NavigationBar variant=\"home\" … />} tabBar={<TabBar … />}>… scrolling screen content …</PageShell>"
+  },
+  "spec": "page-shell.md",
+  "subcomponents": [
+    { "slug": "page-shell", "md": "page-shell.md", "default": true, "specMissing": true }
+  ]
+}

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

@@ -0,0 +1,51 @@
+# PageShell
+
+The app scaffold that **pins** `NavigationBar` (top) and `TabBar` (bottom) while only the body scrolls.
+
+## Why it exists
+
+Chorus bars render **in flow** and do **not** self-pin — they only pay their own `env(safe-area-inset-*)`. Pinning is the shell's job. The most common bug is rendering the bars inside the scrolling region (window-scroll + `padding-bottom`, or a tall scrolling `<div>`): the screen looks fine when short, but on a long list the bars scroll away with the content. The fix is a full-height flex column where only `<main>` scrolls.
+
+## Anatomy
+
+```jsx
+<PageShell
+  nav={<NavigationBar variant="main" … />}
+  tabBar={<TabBar … />}
+>
+  {/* the ONLY part that scrolls */}
+  <Feed … />
+  <List … />
+</PageShell>
+```
+
+renders:
+
+```html
+<div class="chorus-page-shell">      <!-- display:flex; flex-direction:column; height:100dvh -->
+  …nav…                              <!-- flow child, natural height -->
+  <main class="chorus-page-shell__body">  <!-- flex:1 1 auto; min-height:0; overflow-y:auto; overscroll-behavior:contain -->
+    …children…
+  </main>
+  …tabBar…                           <!-- flow child, natural height -->
+</div>
+```
+
+## Props
+
+| prop | type | notes |
+|---|---|---|
+| `nav` | node | rendered in flow at the top (a `NavigationBar`). Pays its own safe-area-inset-top. |
+| `tabBar` | node | rendered in flow at the bottom (a `TabBar`). Pays its own safe-area-inset-bottom. |
+| `children` | node | the scrolling body content (the sole scroll region). |
+| `bodyProps` | object | 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` | string | added to the shell root. |
+
+## Rules
+
+- **Do not** give `NavigationBar` / `TabBar` `position: sticky` / `fixed` — that double-applies their safe-area insets. The flex shell is the pin.
+- `min-height: 0` on the body is load-bearing — it lets the body (not the shell) shrink and scroll. It ships in the `.chorus-page-shell__body` class, so use the component / class rather than hand-authoring it.
+- PageShell owns only the pin/scroll mechanics, not a content gutter — the body honors the normal full-bleed / inline padding contract.
+- 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.
+
+A dev-only guard (`usePinnedBarGuard`) warns in the console when a bar is rendered inside a scrolling region instead of a shell. See also `patterns/layout.md`.