@teamblind-chorus/ui 1.0.0

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

@@ -0,0 +1,91 @@
+# Nav list
+
+A vertical label-only nav list — labelled block where each row carries a label (and an optional supporting line) plus a trailing chevron Icon Button, and routes via `href` / `onClick`. Bundles a [Header](../header/header.md) over a label-only [List](../list/entry.md) `variant="entry"` so the section title and the route group come as one composition. Anatomy is intentionally label-only — `thumbnail` is omitted on every row, the leading column collapses, and the trailing rail carries a default [Icon Button](../button/icon.md) with a right-pointing chevron.
+
+**Reach for this when** the screen shows a category index, settings menu, or any "pick a sub-page" set where each row is purely a route target. **Skip when** the rows need a leading thumbnail (use [DirectoryList](../directory-list/directory-list.md)) or the rows commit in place rather than route (use [List](../list/standard.md) `variant="standard"`).
+
+**Layout inset.** `full-bleed` — sits as a direct child of the page shell (or any host that pays the gutter). Container pays its own `24px block / 16px inline` padding; each row keeps the list/entry native `16px inline padding` for the tap target and pulls its inline margin by `-16` so the visible label lines up with the header label at 16 from the surface. Do **not** wrap 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
+
+Header label only, nine category rows with trailing chevrons.
+
+```preview
+nav-list/default
+---
+import { NavList } from '@teamblind-chorus/ui';
+
+<NavList
+  label="Category"
+  items={[
+    { value: 'location',      label: 'Location',              href: '/category/location' },
+    { value: 'job',           label: 'Job Function',          href: '/category/job-function' },
+    { value: 'learning',      label: 'Learning & Advising',   href: '/category/learning' },
+    { value: 'money',         label: 'Money',                 href: '/category/money' },
+    { value: 'industry',      label: 'Industry',              href: '/category/industry' },
+    { value: 'worklife',      label: 'Work Life',             href: '/category/work-life' },
+    { value: 'entertainment', label: 'Entertainment',         href: '/category/entertainment' },
+    { value: 'relationships', label: 'Relationships & Social',href: '/category/relationships' },
+    { value: 'culture',       label: 'Culture',               href: '/category/culture' },
+  ]}
+/>
+```
+
+## Use cases
+
+### With header action
+
+Extends the header with a trailing `accent` Text Button when the screen has a broader index page or "Manage" route.
+
+```preview
+nav-list/with-header-action
+---
+import { NavList } from '@teamblind-chorus/ui';
+
+<NavList
+  label="Settings"
+  headerAction={{ label: 'Manage', href: '/settings/manage' }}
+  items={[
+    { value: 'account',      label: 'Account',       href: '/settings/account' },
+    { value: 'notifications',label: 'Notifications', href: '/settings/notifications' },
+    { value: 'privacy',      label: 'Privacy',       href: '/settings/privacy' },
+    { value: 'appearance',   label: 'Appearance',    href: '/settings/appearance' },
+    { value: 'language',     label: 'Language',      href: '/settings/language' },
+  ]}
+/>
+```
+
+## Slots
+
+- **container** — `surface` block with 24px block / 16px inline padding. Holds the header above the vertical nav list.
+- **header** — [Header](../header/header.md) `size="large"`. Section label leading, optional accent Text Button trailing. Anchored above the list.
+- **list** — embedded [List](../list/entry.md) `variant="entry"` carrying the rows. `thumbnail` is omitted on every row (leading column collapses); the row's `trailingIcon` slot is filled with a default chevron Icon Button.
+- **row** — single nav row rendered by [List](../list/entry.md) as a label-only entry. The label is the primary content; the trailing Icon Button signals drill-in.
+- **trailingChevron** — default [Icon Button](../button/icon.md) (`variant="icon"`, `size="medium"`) filled with a right-pointing `ChevronRightIcon`. Wired to the row's `href` / `onClick` so the trailing slot is a separate hit target.
+
+## Anatomy
+
+| Slot           | Token bindings |
+|----------------|----------------|
+| container      | `surface` fill, 24px block / 16px inline padding, vertical stack |
+| header         | [Header](../header/header.md) `size="large"`. Container stack (`sys.layout.stack.md` = 16px) separates from list. |
+| label          | `heading.md` / Semibold / `onSurface` |
+| headerAction   | `xsmall` [Text Button](../button/text.md), `accent` appearance |
+| list           | [List](../list/entry.md) `variant="entry"`. `embedded` (wrapper section owns the rail). Label-only — `thumbnail` is omitted on every row so the leading column collapses and the label sits flush at the 16 inline rail. |
+| row            | [list/entry](../list/entry.md)-shaped label-only row — label.md primary / label.sm `description` (optional). Keeps the list/entry native `container.md` inline padding and adds `margin-inline: -container.md` so the label lines up at the section rail (16 from the surface). Divider falls back to the default 16/16 inset (no avatar column to anchor against). |
+| trailingChevron| Default [Icon Button](../button/icon.md) — `variant="icon"`, `size="medium"`, `icon={<ChevronRightIcon />}`. Glyph at `sys.icon.md` / `onSurfaceVariant`. |
+
+## States
+
+Each row body is the interactive route target — hover / pressed / focused / disabled tokens delegate to [List](../list/entry.md). The trailing chevron Icon Button paints its own state per [Icon Button](../button/icon.md) and wires the same route — clicks on the icon stop propagating before reaching the row, so the trailing slot is its own hit target. The **headerAction** is an `xsmall` Text Button (rendered as `<a>` when `href` is set).
+
+## Focus indicator
+
+Row body takes the family-wide Inward focus ring (per [List](../list/entry.md)); the trailing chevron Icon Button paints its own Outward ring; headerAction paints its own Outward ring.
+
+## Behavior
+
+- **Header is required.** Every NavList carries a `label`; the optional `headerAction` extends the header with a trailing `accent` Text Button when there's an index page to route to.
+- **Vertical scroll, no pager.** The full list scrolls in normal document flow.
+- **Each row routes.** Rows render as `<a>` when `href` is set; otherwise `onClick` fires. The trailing chevron Icon Button mirrors the same route so the trailing slot is a redundant — but independently focusable — affordance.
+- **Label-only by design.** The wrapper does not expose a `thumbnail` prop on `items`; the underlying [list/entry](../list/entry.md) keeps the leading slot collapsed for every row. Reach for [DirectoryList](../directory-list/directory-list.md) when a leading avatar is needed.

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

@@ -0,0 +1,107 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "NavList",
+  "family": "nav-list",
+  "description": "Vertical label-only nav list — labelled block where each row carries a label and a trailing chevron [Icon Button](../button/icon.md), and routes via `href` / `onClick`. Bundles a [Header](../header/header.md) over a label-only [List](../list/entry.md) `variant=\"entry\"` (every row drops `thumbnail` so the leading column collapses). Reach for it on category indexes, settings menus, and 'pick a sub-page' surfaces.",
+  "element": "section",
+  "props": {
+    "embedded": {
+      "type": "boolean",
+      "default": false,
+      "description": "Composition mode flag. When `true` (or when NavList is a direct child of `.chorus-carousel` / `.chorus-feed`), the list enters **embedded mode**: zeroes its own `background` + `padding` so chrome defers to the host."
+    },
+    "label": {
+      "type": "string",
+      "required": true,
+      "description": "Section title."
+    },
+    "headerAction": {
+      "type": "object",
+      "optional": true,
+      "description": "{ label, href?, onClick? } — trailing accent Text Button in the header. Extend the header when there's an index page to route to."
+    },
+    "items": {
+      "type": "node",
+      "required": true,
+      "description": "Array of nav row descriptors forwarded to [List](../list/entry.md) `variant=\"entry\"` as label-only rows: { value, label, supportingText?, href?, onClick?, trailingIcon? }. `supportingText` is mapped to the entry sub's `description` slot (caption-tone supporting line under the label). `thumbnail` is intentionally NOT exposed — the leading column is always collapsed."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Surface block holding the header above the vertical nav list.",
+      "intrinsic": true
+    },
+    "header": {
+      "required": true,
+      "description": "[Header](../header/header.md) `size=\"large\"` — section label leading, optional `accent` Text Button trailing.",
+      "accepts": ["text", "button"]
+    },
+    "list": {
+      "required": true,
+      "description": "[List](../list/entry.md) `variant=\"entry\"`. Embedded so the wrapper section owns the rail. Every row drops `thumbnail` so the leading column collapses (label-only). Each row is the interactive route target; the row's `trailingIcon` slot is filled with a default chevron [Icon Button](../button/icon.md).",
+      "intrinsic": true
+    },
+    "row": {
+      "required": true,
+      "intrinsic": true,
+      "description": "Single nav row rendered by [List](../list/entry.md) as a label-only entry. The label is the primary content; the trailing chevron Icon Button (`variant=\"icon\"`, `size=\"medium\"`, `icon={<ChevronRightIcon />}`) signals drill-in. Each row routes via `href` or `onClick`.",
+      "accepts": ["row"]
+    },
+    "trailingChevron": {
+      "required": true,
+      "intrinsic": true,
+      "description": "Default [Icon Button](../button/icon.md) (`variant=\"icon\"`, `size=\"medium\"`) filled with `<ChevronRightIcon />`. Wired to the row's `href` / `onClick`. Clicks stop propagating before reaching the row's primary handler — the trailing slot is its own hit target with its own Outward focus ring."
+    }
+  },
+  "sizing": {
+    "containerFill": "sys.color.surface",
+    "containerPaddingBlock": "sys.layout.container.lg",
+    "containerPaddingInline": "sys.layout.container.md",
+    "headerToListGap": "sys.layout.stack.md",
+    "labelTypo": "sys.typo.heading.md",
+    "labelColor": "sys.color.onSurface",
+    "headerActionRendersAs": "Button variant='text' size='xsmall' appearance='accent' — link-affordance accent rule.",
+    "rowComposition": "list/entry label-only row (no thumbnail) — label.md primary, optional label.sm description line, family-default min-height (ref.space.600 = 48), leading column collapsed (0 leading-to-text gap), trailing slot filled with a default Icon Button (variant='icon', size='medium', icon=<ChevronRightIcon />).",
+    "rowInlinePaddingNote": "Each row keeps the list/entry native sys.layout.container.md inline padding (the tap target reaches the surface edge) and adds margin-inline: calc(-1 * sys.layout.container.md) so the visible label lines up with the section's content rail (aligned with the header label at 16 from the surface).",
+    "dividerWidth": "sys.borderWidth.hairline",
+    "dividerColor": "sys.color.outlineVariant",
+    "dividerInset": "list/entry default — 16 / 16 inset from both row edges. Label-only rows always take the default inset regardless of `size` (no avatar column to anchor against)."
+  },
+  "rowProps": {
+    "value": { "type": "string", "required": true },
+    "label": { "type": "string", "required": true },
+    "supportingText": {
+      "type": "string",
+      "optional": true,
+      "description": "Caption-tone supporting line under the label. Mapped to the entry sub's `description` slot — single-line, truncated with ellipsis."
+    },
+    "href": { "type": "string", "optional": true },
+    "onClick": { "type": "function", "optional": true },
+    "trailingIcon": {
+      "type": "node",
+      "optional": true,
+      "description": "Override the default trailing chevron Icon Button with a custom node (e.g. an external-link Icon Button). Should remain a `<Button variant=\"icon\">` so the trailing slot keeps its own Outward focus ring."
+    }
+  },
+  "states": {
+    "note": "Each row body is the interactive route target — hover / pressed / focused / disabled tokens delegate to [List](../list/entry.md). The trailing chevron Icon Button paints its own state per [Icon Button](../button/icon.md); its clicks stop propagating before reaching the row's primary handler. The headerAction is an accent Text Button (its own state contract). Container has no interactive state."
+  },
+  "focusIndicator": {
+    "description": "Row body takes the family-wide Inward focus ring; the trailing chevron Icon Button paints its own Outward ring; headerAction paints its own Outward ring.",
+    "composition": "inward",
+    "compositionReason": "Rows tile the column with a hairline divider; an outward ring on the row body would overlap divider and neighbour row.",
+    "trigger": ":focus-visible"
+  },
+  "behavior": {
+    "headerRequired": "Every NavList carries a label; the optional headerAction extends the header with a trailing accent Text Button.",
+    "verticalScroll": "No pager. The full list scrolls in normal document flow.",
+    "rowRoutes": "Each row routes via `href` (rendered as `<a>`) or `onClick`. The trailing chevron Icon Button mirrors the same route — independent hit target, independent Outward focus ring.",
+    "labelOnly": "The wrapper does not expose a `thumbnail` prop on `items`; the underlying [list/entry](../list/entry.md) keeps the leading slot collapsed for every row."
+  },
+  "forbidden": [
+    "leading thumbnail or icon — NavList rows are intentionally label-only; reach for DirectoryList when a leading visual is needed",
+    "swapping the trailing chevron for a non-Button node — the trailing slot must stay a `<Button variant=\"icon\">` so it keeps its own Outward focus ring",
+    "header omitted — every NavList carries a label"
+  ]
+}

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

@@ -0,0 +1,201 @@
+# Main
+
+The landing-screen top bar — anchored to a tab root (feed, inbox, profile). A leading menu glyph plus left-aligned page name sit at the start; **up to four** trailing icon actions (conventionally search, chat, profile) sit at the end. Title carries the system's largest page-level rung (`typo.heading.lg`, 24/Semibold). The same row also serves a **drill-in (content-detail) screen** — pass `onBack` instead of `onMenuClick` and the leading glyph swaps to a back chevron, with the trailing cluster carrying up to four actions (see [Use cases](#use-cases)).
+
+**Reach for this when** the screen is a tab root and needs the menu drawer plus a small set of global affordances, **or** when it's a content-detail drill-in (a post / article reached from a feed) needing back navigation plus a share-and-save cluster. **Skip when** you need a centred title with a single action (use [Sub](./sub.md)) or are on 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
+
+Menu glyph, brand logotype at 24px tall, three trailing actions.
+
+```preview
+navigation-bar/main/default
+---
+import { NavigationBar } from '@teamblind-chorus/ui';
+import { SearchIcon, ChatIcon, ProfileIcon } from '@teamblind-chorus/ui/icons';
+
+<NavigationBar
+  variant="main"
+  title={
+    <img
+      src="/blind_logotype_black.svg"
+      alt="Chorus"
+      style={{ height: 24, width: 'auto', display: 'block' }}
+    />
+  }
+  onMenuClick={() => {}}
+  trailingActions={[
+    { icon: <SearchIcon />,  'aria-label': 'Search' },
+    { icon: <ChatIcon />,    'aria-label': 'Messages' },
+    { icon: <ProfileIcon />, 'aria-label': 'Profile' },
+  ]}
+/>
+```
+
+## Use cases
+
+### With a text title in place of the logotype
+
+Names the screen in words. Plain text at `typo.heading.lg` (24/Semibold) `onSurface`; same 24-tall rhythm as the logotype, ellipsis on narrow.
+
+```preview
+navigation-bar/main/default--text-title
+---
+import { NavigationBar } from '@teamblind-chorus/ui';
+import { SearchIcon, ChatIcon, ProfileIcon } from '@teamblind-chorus/ui/icons';
+
+<NavigationBar
+  variant="main"
+  title="Home"
+  onMenuClick={() => {}}
+  trailingActions={[
+    { icon: <SearchIcon />,  'aria-label': 'Search' },
+    { icon: <ChatIcon />,    'aria-label': 'Messages' },
+    { icon: <ProfileIcon />, 'aria-label': 'Profile' },
+  ]}
+/>
+```
+
+### With one trailing action
+
+Single trailing affordance — e.g. search on an Inbox screen.
+
+```preview
+navigation-bar/main/single-action
+---
+import { NavigationBar } from '@teamblind-chorus/ui';
+import { SearchIcon } from '@teamblind-chorus/ui/icons';
+
+<NavigationBar
+  variant="main"
+  title="Inbox"
+  trailingActions={[
+    { icon: <SearchIcon />, 'aria-label': 'Search' },
+  ]}
+/>
+```
+
+### Drill-in detail screen (back chevron)
+
+A content-detail screen reached from a feed / list (a post, an article, a saved item). Pass `onBack` — the leading glyph becomes a back chevron — and the trailing cluster carries up to four actions (share / notify / bookmark / more). Same row, same 56-tall geometry; only the entry point differs.
+
+```preview
+navigation-bar/main/detail
+---
+import { NavigationBar } from '@teamblind-chorus/ui';
+import { ShareIcon, BellOffIcon, BookmarkIcon, EllipsisHorizontalIcon } from '@teamblind-chorus/ui/icons';
+
+<NavigationBar
+  variant="main"
+  title={
+    <img
+      src="/blind_logotype_black.svg"
+      alt="Chorus"
+      style={{ height: 24, width: 'auto', display: 'block' }}
+    />
+  }
+  onBack={() => {}}
+  trailingActions={[
+    { icon: <ShareIcon />,              'aria-label': 'Share' },
+    { icon: <BellOffIcon />,            'aria-label': 'Turn off notifications' },
+    { icon: <BookmarkIcon />,           'aria-label': 'Save' },
+    { icon: <EllipsisHorizontalIcon />, 'aria-label': 'More' },
+  ]}
+/>
+```
+
+### Drill-in with a text title and a smaller cluster
+
+Names the source — the channel or author the post belongs to. The cluster is `1..4` actions; drop to just the essentials (share + more) when the screen has fewer affordances.
+
+```preview
+navigation-bar/main/detail-text-title
+---
+import { NavigationBar } from '@teamblind-chorus/ui';
+import { ShareIcon, EllipsisHorizontalIcon } from '@teamblind-chorus/ui/icons';
+
+<NavigationBar
+  variant="main"
+  title="Sourdough Bakers"
+  onBack={() => {}}
+  trailingActions={[
+    { icon: <ShareIcon />,              'aria-label': 'Share' },
+    { icon: <EllipsisHorizontalIcon />, 'aria-label': 'More' },
+  ]}
+/>
+```
+
+### Truncation (safety net)
+
+Long page name truncates with ellipsis. Author concise titles (*Home*, *Inbox*) so the bar never resorts to ellipsis.
+
+```preview
+navigation-bar/main/truncation
+---
+import { NavigationBar } from '@teamblind-chorus/ui';
+import { SearchIcon, ChatIcon, ProfileIcon } from '@teamblind-chorus/ui/icons';
+
+<NavigationBar
+  variant="main"
+  title="A very long screen title that should truncate"
+  onMenuClick={() => {}}
+  trailingActions={[
+    { icon: <SearchIcon />,  'aria-label': 'Search' },
+    { icon: <ChatIcon />,    'aria-label': 'Messages' },
+    { icon: <ProfileIcon />, 'aria-label': 'Profile' },
+  ]}
+/>
+```
+
+## Slots
+
+- **leadingIcon** *(intrinsic)* — the menu / hamburger ([`MenuIcon`](../../icons/svg/Menu.svg)) on a tab root (the hook into the app's primary drawer), or a back chevron ([`ChevronLeftIcon`](../../icons/svg/ChevronLeft.svg), wired to `onBack`) on a drill-in / content-detail screen. Never an arbitrary glyph.
+- **title** — screen identity. Required. Default is the brand logotype at fixed 24px height (ratio preserved); a string may be passed instead — renders as `typo.heading.lg` (24/Semibold) `onSurface`, ellipsis on narrow.
+- **trailingActions** *(optional)* — up to four icon actions (three conventional on a tab root: Search, Chat, Profile; up to four for the drill-in cluster: Share, Notify, Bookmark, More). Laid left-to-right with no inter-icon gap — the capsules' 8px padding provides visible separation. The component slices a fifth.
+
+## Anatomy
+
+| Slot                  | Container          | Color                                   |
+|-----------------------|--------------------|------------------------------------------|
+| **Bar container**     | `sys.color.surface` fill, 8px block / 16px inline padding, no border, no shadow at rest. | — |
+| **Leading icon**      | Transparent capsule, 24px glyph centred. | `sys.color.onSurface` |
+| **Title**             | Brand logotype `<img>` at 24px tall (width auto) by default; plain-text fallback at `heading.lg`. Not interactive. | `sys.color.onSurface` (text fallback) |
+| **Trailing icon(s)**  | Transparent capsule, 24px glyph centred. Capsules sit flush, no inter-icon gap. | `sys.color.onSurface` |
+
+## 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 ‡                              |
+| Slot gap (leading ↔ title)        | 16px                 | `sys.layout.inline.xl`             |
+| Slot gap (title ↔ trailing group) | 16px                 | `sys.layout.inline.xl`             |
+| Slot gap (between trailing icons) | 16px                 | `sys.layout.inline.xl` †           |
+| Icon-capsule padding              | 8px                  | `sys.layout.container.xs`          |
+| Title — brand logotype (default)  | 24px tall, width auto| raw — fixed pixel height           |
+| Title — plain text (fallback)     | 24 / Semibold        | `sys.typo.heading.lg`              |
+| Leading icon                      | 24px                 | `sys.icon.lg`                      |
+| Trailing icon                     | 24px                 | `sys.icon.lg`                      |
+
+‡ Floor of 8 + 40 + 8 = 56. Keeps a title-only row from collapsing below 56.
+
+† Optical alignment via Icon Button's negative-margin bleed — chrome-to-chrome 16 *is* the visible glyph-to-glyph distance.
+
+## States
+
+The bar itself has no interactive state. Icon slots inherit [Icon Button](../button/icon.md) states. Title carries no states.
+
+## Focus indicator
+
+Bar isn't a focus target; icon slots inherit [Icon Button → Outward](../button/icon.md#focus-indicator). Trigger: `:focus-visible`.
+
+## Behavior
+
+- **Bar is page chrome.** Renders in flow; host pins (`position: sticky`) when needed.
+- **Title truncates.** Long page names truncate; bar height stays 56. Safety net only — page names should be one or two words.
+- **Trailing icon count.** Three is the conventional ceiling on a tab root; the drill-in cluster uses up to four (share / notify / bookmark / more). A fifth belongs in the `more` (•••) overflow — the component slices to four.
+- **Leading affordance.** Menu glyph on a tab root (`onMenuClick`); back chevron on a drill-in (`onBack`). `onBack` wins if both are passed; with neither, the menu is the default.

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

@@ -0,0 +1,109 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "NavigationBar",
+  "family": "navigation-bar",
+  "subcomponent": "main",
+  "exportAlias": "AppBar",
+  "exportAliasNote": "The `AppBar` runtime alias re-exports the family-level `<NavigationBar>` component (not just the main sub) so consumers can drop in `<AppBar variant=\"main|sub|search\">`. Declared on the main sub-spec because Main is the canonical default landing for `AppBar`-style consumers; the family-level export is what actually ships from packages/ui/src/index.js.",
+  "description": "Landing-screen top bar — anchored to the top of a tab root (a feed, an inbox, a profile, a discover screen). A leading menu glyph + left-aligned title occupy the start of the row; up to four action icons (search, chat, profile / notifications) sit at the trailing edge. **The title slot defaults to the brand logotype rendered at 24px tall** (width auto, ratio preserved) so the landing rung of every Main tab opens with the product mark rather than a written page name. A string title is the fallback for screens that don't anchor a top-level brand identity (a secondary tab root, a feature surface, a dev screen); the fallback carries the system's largest page-level type rung (heading.lg, 24/Semibold) rather than the smaller drill-in rung used by Sub, and shares the 24-tall rhythm of the logotype so the bar's height is unchanged across the two presentations. **Drill-in (content-detail) case:** the same row serves a content-detail screen reached from a feed / list (a post, an article, a saved item) — pass `onBack` instead of `onMenuClick` and the leading glyph swaps from menu to a back chevron; the trailing cluster then carries up to four actions (share / notify / bookmark / more).",
+  "element": "header",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "main"
+    },
+    "title": {
+      "type": "node",
+      "required": true,
+      "description": "Default: brand logotype `<img>` rendered at a fixed 24px height (width auto). Fallback: plain string rendered as `heading.lg` text that truncates with ellipsis."
+    },
+    "onMenuClick": {
+      "type": "function",
+      "optional": true,
+      "description": "Tab-root case — fires when the leading menu / hamburger is tapped (opens the app drawer). Mutually exclusive with `onBack`."
+    },
+    "onBack": {
+      "type": "function",
+      "optional": true,
+      "description": "Drill-in (content-detail) case — passing `onBack` swaps the leading menu glyph for a back chevron wired to it (route to the previous screen). Takes precedence over `onMenuClick` when both are passed."
+    },
+    "backLabel": {
+      "type": "string",
+      "optional": true,
+      "description": "Accessible label for the back chevron in the drill-in case. Defaults to \"Back\"."
+    },
+    "trailingActions": {
+      "type": "node",
+      "optional": true,
+      "description": "Up to four { icon, 'aria-label' } entries; laid out left-to-right with no inter-icon gap. Three is the conventional ceiling on a tab root; the drill-in (content-detail) cluster uses up to four (share / notify / bookmark / more)."
+    }
+  },
+  "slots": {
+    "leadingIcon": {
+      "required": true,
+      "intrinsic": true,
+      "description": "Intrinsic — the menu / hamburger glyph (MenuIcon) on a tab root, or a back chevron (ChevronLeftIcon, wired to `onBack`) on a drill-in / content-detail screen. Rendered as a transparent icon capsule with the 24px glyph centred. Never an arbitrary custom glyph.",
+      "accepts": [
+        "icon"
+      ]
+    },
+    "title": {
+      "required": true,
+      "description": "Screen's identity. Default rendering is the brand logotype `<img>` at a fixed 24px height (width auto, ratio preserved) so every Main tab opens with the product mark. Falls back to a plain-text string at heading.lg / Semibold / onSurface (truncates with ellipsis) when the screen has no logotype affordance.",
+      "accepts": [
+        "text",
+        "image"
+      ]
+    },
+    "trailingActions": {
+      "required": false,
+      "description": "Array of up to four icon actions at the end of the row (three conventional on a tab root; up to four for the drill-in action cluster). Each renders as a transparent icon capsule; capsules sit flush with no inter-icon gap.",
+      "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.",
+    "leadingTitleGap": "sys.layout.inline.xl",
+    "titleTrailingGap": "sys.layout.inline.xl",
+    "trailingIconGap": "sys.layout.inline.xl",
+    "iconCapsulePadding": "sys.layout.container.xs",
+    "titleLogotypeHeight": "ref.space.300",
+    "titleTypo": "sys.typo.heading.lg",
+    "leadingIconSize": "sys.icon.lg",
+    "trailingIconSize": "sys.icon.lg"
+  },
+  "appearance": {
+    "containerFill": "sys.color.surface",
+    "leadingIconColor": "sys.color.onSurface",
+    "titleColor": "sys.color.onSurface",
+    "trailingIconColor": "sys.color.onSurface"
+  },
+  "states": {
+    "note": "Bar itself has no interactive state. Icon slots carry the standard Icon Button state recipe — default / hovered (sys.state.hover overlay) / pressed (sys.state.pressed overlay) / disabled / focused (three-layer focus ring). Title carries no states."
+  },
+  "focusIndicator": {
+    "description": "The bar itself isn't a focus target. Its action slots (leading menu, trailing icons) inherit each control's own focus composition — Icon Button → Outward — so the ring belongs to whichever capsule the keyboard lands on. See the contained sub-components for the visual contract.",
+    "composition": "delegated",
+    "delegatesTo": "../button/icon.spec.json#/focusIndicator",
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "behavior": {
+    "pageChrome": "Bar renders in the page flow at the top of the screen; the host page is responsible for pinning (position: sticky, etc.).",
+    "titleTruncates": "Long page names truncate with ellipsis; the bar height stays at 56 regardless. Treat as a safety net — author concise titles.",
+    "trailingIconCeiling": "Three is the conventional ceiling on a tab root; the drill-in (content-detail) action cluster uses up to four (share / notify / bookmark / more). A fifth belongs in the `more` (•••) overflow — the component slices to four."
+  },
+  "forbidden": [
+    "brand color on the title / wordmark — header chrome stays on sys.color.surface; the wordmark paints sys.color.onSurface",
+    "more than four trailing actions — the action cluster caps at four; a fifth belongs in the `more` overflow",
+    "leading glyph other than the menu (tab root) or back chevron (drill-in, via onBack) — never an arbitrary custom glyph",
+    "centred title — the Main title is left-aligned next to the leading glyph (a centred title is the `sub` variant)",
+    "title bar height different from 56px — geometry is fixed across all navigation-bar subs"
+  ]
+}

package/agents/components/navigation-bar/navigation-bar.family.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "navigation-bar",
+  "name": "NavigationBar",
+  "description": "Top-bar family. `main` is the landing-screen bar (menu glyph + left-aligned title + trailing action icons) — and the same bar serves a content-detail drill-in when given `onBack`, which swaps the menu glyph for a back chevron and lets the trailing cluster carry up to four actions (share / notify / bookmark / more); `sub` is the drill-in bar (centred title + leading back / single trailing action); `search` is the search-page bar (leading back + bare-text input filling the row + conditional clear). All ride the same 56px min-height and 8/8 padding so they stay at one geometry across a navigation flow.",
+  "useCases": [
+    "screen header",
+    "landing-screen top bar",
+    "post / content detail top bar",
+    "drill-in top bar",
+    "search top bar",
+    "back navigation"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "full-bleed",
+  "wrapperGuidance": "Owns its inline padding internally. Place as a direct child of the page-shell <main> (or any host that pays the gutter once). Do NOT wrap in a padding-inline div, className=\"px-*\", or style={{ padding }} \u2014 the page rail is paid once at the shell, never on the full-bleed child. Inside a bounded surface (Dialog / BottomSheet / SideSheet), apply the negative-margin opt-out \u2014 see AGENTS.md \u00a7 Composition rules.",
+  "spec": "navigation-bar.md",
+  "usage": {
+    "note": "All three bars are the single `NavigationBar` export selected by the `variant` prop — pass `onBack` to a `main` bar to turn it into a content-detail drill-in. Also exported as the alias `AppBar`.",
+    "subs": {
+      "main": { "variant": "main", "example": "<NavigationBar variant=\"main\" title=\"Home\" trailingActions={[{ icon, 'aria-label' }]} />" },
+      "sub": { "variant": "sub", "example": "<NavigationBar variant=\"sub\" title=\"Edit profile\" leading={{ icon, 'aria-label' }} trailing={<Button variant=\"toolbar\">Save</Button>} />" },
+      "search": { "variant": "search", "example": "<NavigationBar variant=\"search\" placeholder=\"Search by keyword\" onBack={() => {}} />" }
+    }
+  },
+  "subcomponents": [
+    {
+      "slug": "main",
+      "spec": "main.spec.json",
+      "md": "main.md",
+      "default": true
+    },
+    {
+      "slug": "sub",
+      "spec": "sub.spec.json",
+      "md": "sub.md"
+    },
+    {
+      "slug": "search",
+      "spec": "search.spec.json",
+      "md": "search.md"
+    }
+  ]
+}

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

@@ -0,0 +1,21 @@
+# Navigation bar
+
+The top app bar — a horizontal strip pinned to the top of a screen that names the screen and exposes its highest-priority actions. Three sub-flavors share this contract: **Main** (landing-screen bar), **Sub** (drill-in bar with centred title), and **Search** (search-page bar with a bare-text input). All three sit at 16px inline / 8px block padding and delegate icon slots to [Icon Button](../button/icon.md).
+
+**Layout inset.** `full-bleed` — sits flush at the top of the page shell. The bar owns its own `16px inline / 8px block` padding via `layout.container.*`; do **not** wrap it in another `padding-inline` / `px-*` / `style={{ padding: … }}` div. The bar is pinned chrome, not a `<main>` child — sits *outside* the `<main>` that pays `sys.layout.page.*`. See [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+**Viewport safe area.** The bar's block padding stacks `env(safe-area-inset-top)` on top of the canonical `container.xs` (8) breathing room — so its `surface` background extends through the device status-bar / notch zone above the 56-tall content row, and scrolled body content does not bleed through the transparent system chrome. On non-mobile viewports `env()` resolves to 0 and the bar collapses to its original 8 / 16 padding. **The page shell MUST NOT add its own `padding-top: env(safe-area-inset-top)` when a NavigationBar is rendered at the top** — the bar already pays it, and stacking would double-inset the row by the notch height.
+
+## Cross-sub contract
+
+- **Container.** Horizontal strip with **16px inline + 8px block padding** (`sys.layout.container.md` × `sys.layout.container.xs`), `surface` fill, **min-height 56**. Inter-slot gap is `sys.layout.inline.xl` (16).
+- **Slots.** A **leading** slot (icon), a **centre slot** (title text on Main/Sub; bare input on Search), and a **trailing** slot (up to four icons on Main; a single button / link / icon on Sub; conditional clear (×) on Search). Titles truncate with ellipsis; Search input never reflows its leading edge.
+- **Icon slots are [Icon Buttons](../button/icon.md).** Every icon slot renders as a 40 × 40 transparent capsule hosting a 24px (`sys.icon.lg`) glyph.
+- **Title is not interactive.**
+- **Accessibility.** Bar exposes `role="banner"` (Main, as main banner) or no implicit role (Sub — page chrome). Icon slots carry `aria-label`; the page's `<h1>` lives in the page body.
+
+## Sub-components
+
+- **[Main](./main.md)** — Landing-screen top bar. Left-aligned page name (`typo.heading.lg`, 24/Semibold) preceded by a leading menu icon; up to four trailing action icons. The same bar serves a content-detail drill-in when given `onBack` — the leading glyph becomes a back chevron and the trailing cluster carries up to four actions. Min-height 56.
+- **[Sub](./sub.md)** — Drill-in top bar. Centred page name (`typo.heading.sm`, 16/Semibold); leading back-arrow and a trailing slot ([Toolbar Button](../button/toolbar.md), text link, or single icon). Min-height 56.
+- **[Search](./search.md)** — Search-page top bar. Leading back-arrow Icon Button, a single bare-text input filling the middle column, and a conditional clear (×) Icon Button. No title slot. Min-height 56.