@teamblind-chorus/ui 1.1.0 → 2.0.0

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

@@ -2,7 +2,7 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/navigation-bar/main.md`](../../../i18n/ko/schema/components/navigation-bar/main.md)
 
-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)).
+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 [Drill-in](#drill-in)).
 
 **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)).
 
@@ -36,9 +36,7 @@ import { SearchIcon, ChatIcon, ProfileIcon } from '@teamblind-chorus/ui/icons';
 />
 ```
 
-## Use cases
-
-### With a text title in place of the logotype
+## Text title
 
 Names the screen in words. Plain text at `typo.heading.lg` (24/Semibold) `onSurface`; same 24-tall rhythm as the logotype, ellipsis on narrow.
 
@@ -60,7 +58,7 @@ import { SearchIcon, ChatIcon, ProfileIcon } from '@teamblind-chorus/ui/icons';
 />
 ```
 
-### With one trailing action
+## Single action
 
 Single trailing affordance — e.g. search on an Inbox screen.
 
@@ -79,7 +77,7 @@ import { SearchIcon } from '@teamblind-chorus/ui/icons';
 />
 ```
 
-### Drill-in detail screen (back chevron)
+## Drill-in
 
 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.
 
@@ -108,7 +106,7 @@ import { ShareIcon, BellOffIcon, BookmarkIcon, EllipsisHorizontalIcon } from '@t
 />
 ```
 
-### Drill-in with a text title and a smaller cluster
+## Drill-in text title
 
 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.
 
@@ -129,7 +127,7 @@ import { ShareIcon, EllipsisHorizontalIcon } from '@teamblind-chorus/ui/icons';
 />
 ```
 
-### Truncation (safety net)
+## Truncation
 
 Long page name truncates with ellipsis. Author concise titles (*Home*, *Inbox*) so the bar never resorts to ellipsis.
 
@@ -162,9 +160,9 @@ import { SearchIcon, ChatIcon, ProfileIcon } from '@teamblind-chorus/ui/icons';
 | 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` |
+| **Leading icon**      | Transparent capsule, 24px glyph centred. | `sys.color.text.default` |
+| **Title**             | Brand logotype `<img>` at 24px tall (width auto) by default; plain-text fallback at `heading.lg`. Not interactive. | `sys.color.text.default` (text fallback) |
+| **Trailing icon(s)**  | Transparent capsule, 24px glyph centred. Capsules sit flush, no inter-icon gap. | `sys.color.text.default` |
 
 ## Sizes
 

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

@@ -80,13 +80,13 @@
     "trailingIconSize": "sys.icon.lg"
   },
   "appearance": {
-    "containerFill": "sys.color.surface",
-    "leadingIconColor": "sys.color.onSurface",
-    "titleColor": "sys.color.onSurface",
-    "trailingIconColor": "sys.color.onSurface"
+    "containerFill": "sys.color.surface.default",
+    "leadingIconColor": "sys.color.icon.default",
+    "titleColor": "sys.color.text.default",
+    "trailingIconColor": "sys.color.icon.default"
   },
   "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."
+    "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 (single 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.",
@@ -100,7 +100,7 @@
     "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",
+    "brand color on the title / wordmark — header chrome stays on sys.color.surface.default; the wordmark paints sys.color.text.default",
     "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)",

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

@@ -20,9 +20,7 @@ import { NavigationBar } from '@teamblind-chorus/ui';
 <NavigationBar variant="search" placeholder="Search by keyword" onBack={() => {}} />
 ```
 
-## Use cases
-
-### With value (clear visible)
+## Value
 
 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.
 
@@ -42,7 +40,7 @@ import { NavigationBar } from '@teamblind-chorus/ui';
 ## 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).
+- **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.text.default`, placeholder in `sys.color.border.boldest` (`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
@@ -51,10 +49,10 @@ Three-column grid (leading / input / trailing) — side columns size to content,
 
 | 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`                                                          |
+| **Bar container**     | `sys.color.surface` fill, 8px block / 16px inline padding, no shadow at rest, **1px bottom divider in `sys.color.border.default`** painted as inset `box-shadow`. | —                                                                              |
+| **Leading**           | Transparent Icon Button capsule (8 padding around 24px glyph).                           | `sys.color.text.default`                                                          |
+| **Input**             | Bare text — no border, no background, no inset stroke.                                   | Value: `sys.color.text.default`. Placeholder: `sys.color.border.boldest`. Caret: `sys.color.background.primary`. |
+| **Trailing (clear)**  | Transparent Icon Button **medium** capsule (32 × 32, 16px glyph).                        | `sys.color.text.default`                                                          |
 
 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.
 

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

@@ -65,7 +65,7 @@
     },
     "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.",
+      "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.text.default` when present; renders the placeholder in `sys.color.border.boldest` 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"
       ]
@@ -91,20 +91,20 @@
     "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"
+    "containerFill": "sys.color.surface.default",
+    "containerBottomDivider": "sys.color.border.default",
+    "leadingColor": "sys.color.text.default",
+    "inputText": "sys.color.text.default",
+    "inputPlaceholder": "sys.color.border.boldest",
+    "inputCaret": "sys.color.text.default",
+    "trailingColor": "sys.color.text.default"
   },
   "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.",
+    "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 + single 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",

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

@@ -25,9 +25,7 @@ import { NavigationBar, Button } from '@teamblind-chorus/ui';
 />
 ```
 
-## Use cases
-
-### With icon trailing
+## Icon trailing
 
 The trailing slot carries a single icon.
 
@@ -44,7 +42,7 @@ import { NavigationBar } from '@teamblind-chorus/ui';
 />
 ```
 
-### With text button trailing
+## 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.
 
@@ -61,7 +59,7 @@ import { NavigationBar } from '@teamblind-chorus/ui';
 />
 ```
 
-### Text button pair (composer)
+## Text Button pair
 
 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).
 
@@ -77,7 +75,7 @@ import { Button, NavigationBar } from '@teamblind-chorus/ui';
 />
 ```
 
-### External page (close-only)
+## External page
 
 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).
 
@@ -93,7 +91,7 @@ import { NavigationBar } from '@teamblind-chorus/ui';
 />
 ```
 
-### Title only
+## Title only
 
 Both side slots empty — for non-dismissible sub-pages (forced confirmation, terms gate).
 
@@ -108,7 +106,7 @@ import { NavigationBar } from '@teamblind-chorus/ui';
 />
 ```
 
-### Overlay (on hero / cover image)
+## Overlay
 
 `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.
 
@@ -137,9 +135,9 @@ import { ProfileHeader } from '@teamblind-chorus/ui';
 | 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) |
+| **Leading**           | Transparent icon capsule (8 padding around 24px glyph). | `sys.color.text.default` |
+| **Title**             | Plain text, centred horizontally — not interactive. | `sys.color.text.default` |
+| **Trailing**          | Transparent icon capsule, [Toolbar Button](../button/toolbar.md), or [Text Button](../button/text.md). | `sys.color.text.default` (icon / Toolbar) or `sys.color.background.primary` (Text Button) |
 
 ## Sizes
 

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

@@ -17,7 +17,7 @@
         "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."
+      "description": "Container fill and foreground tone. `surface` (default) — opaque `sys.color.surface.default` 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",
@@ -74,11 +74,11 @@
   },
   "appearances": {
     "surface": {
-      "containerFill": "sys.color.surface",
-      "leadingColor": "sys.color.onSurface",
-      "titleColor": "sys.color.onSurface",
-      "trailingColor": "sys.color.onSurface",
-      "trailingTextButtonColor": "sys.color.primary",
+      "containerFill": "sys.color.surface.default",
+      "leadingColor": "sys.color.text.default",
+      "titleColor": "sys.color.text.default",
+      "trailingColor": "sys.color.text.default",
+      "trailingTextButtonColor": "sys.color.text.link",
       "default": true,
       "note": "Canonical page chrome — opaque surface fill with onSurface foreground."
     },
@@ -96,7 +96,7 @@
     "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."
+    "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 + single 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.",

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/pagination/pagination.family.json

@@ -2,7 +2,7 @@
   "$schema": "../../family.schema.json",
   "family": "pagination",
   "name": "Pagination",
-  "description": "Decorative dot-position indicator for one-page-at-a-time pagers. An inline element (`span` / inline-flex) sized to its dots — one 6px dot per page; the active dot paints `sys.color.onSurface`, the rest paint `sys.color.outlineVariant`. Presentational only (`aria-hidden`) — the host pager owns horizontal placement (the carousels center it), scroll position, active-index tracking, and keyboard reach; tapping a dot does not navigate. Renders nothing below two pages. Single appearance, single rung. Single-spec family.",
+  "description": "Decorative dot-position indicator for one-page-at-a-time pagers. An inline element (`span` / inline-flex) sized to its dots — one 6px dot per page; the active dot paints `sys.color.text.default`, the rest paint `sys.color.border.default`. Presentational only (`aria-hidden`) — the host pager owns horizontal placement (the carousels center it), scroll position, active-index tracking, and keyboard reach; tapping a dot does not navigate. Renders nothing below two pages. Single appearance, single rung. Single-spec family.",
   "useCases": [
     "carousel page position (PostCarousel / ProfileCarousel)",
     "swipeable media gallery position",

package/agents/components/pagination/pagination.md

@@ -2,7 +2,7 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/pagination/pagination.md`](../../../i18n/ko/schema/components/pagination/pagination.md)
 
-Decorative dot-position indicator for one-page-at-a-time pagers — an inline row of 6px dots, one per page, the active dot painted `sys.color.onSurface` and the rest `sys.color.outlineVariant`.
+Decorative dot-position indicator for one-page-at-a-time pagers — an inline row of 6px dots, one per page, the active dot painted `sys.color.text.default` and the rest `sys.color.border.default`.
 
 **Reach for this when** a horizontally-snapping pager needs to show where the user is — carousel cards ([PostCarousel](../carousel/post.md), [ProfileCarousel](../carousel/profile.md)), a swipeable media gallery, an onboarding pager. **Skip when** the position is a task-completion ratio (use [Progress](../progress/progress.md)), the pages need direct tap-to-jump navigation (dots here are non-interactive — use [Tabs](../tabs/tabs.md)), or the pager has only one page (the component renders nothing below two).
 
@@ -22,14 +22,14 @@ import { Pagination } from '@teamblind-chorus/ui';
 
 ## Slots
 
-- **dot** *(decorative, one per page)* — 6 × 6 (`ref.space.75`), `sys.radius.full`. Active paints `sys.color.onSurface`; inactive paints `sys.color.outlineVariant`.
+- **dot** *(decorative, one per page)* — 6 × 6 (`ref.space.75`), `sys.radius.full`. Active paints `sys.color.text.default`; inactive paints `sys.color.border.default`.
 
 ## Anatomy
 
 | Slot | Token bindings |
 |------|----------------|
 | row  | inline element — `display: inline-flex`, intrinsic width, `sys.layout.inline.sm` gap, `aria-hidden`; horizontal placement belongs to the host |
-| dot  | 6 × 6 (`ref.space.75`), `sys.radius.full`; active `sys.color.onSurface`, inactive `sys.color.outlineVariant` |
+| dot  | 6 × 6 (`ref.space.75`), `sys.radius.full`; active `sys.color.text.default`, inactive `sys.color.border.default` |
 
 ## Behavior
 

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

@@ -2,7 +2,7 @@
   "$schema": "../../spec.schema.json",
   "name": "Pagination",
   "family": "pagination",
-  "description": "Decorative dot-position indicator for one-page-at-a-time pagers. An inline element (`span`, `display: inline-flex`) sized to its dots — it never stretches or centers itself; the host owns horizontal placement (the carousels center it via `align-self: center`). Renders one 6px (`ref.space.75`) fully-rounded dot per page in a `sys.layout.inline.sm` row; the active dot paints `sys.color.onSurface`, the rest paint `sys.color.outlineVariant`. The row is presentational only (`aria-hidden`): the host pager (PostCarousel, ProfileCarousel, a media gallery) tracks the active index — typically via IntersectionObserver on its snap targets — and passes it down; tapping a dot does not navigate. Renders nothing when `count` < 2 — a one-page pager has no position to indicate.",
+  "description": "Decorative dot-position indicator for one-page-at-a-time pagers. An inline element (`span`, `display: inline-flex`) sized to its dots — it never stretches or centers itself; the host owns horizontal placement (the carousels center it via `align-self: center`). Renders one 6px (`ref.space.75`) fully-rounded dot per page in a `sys.layout.inline.sm` row; the active dot paints `sys.color.text.default`, the rest paint `sys.color.border.default`. The row is presentational only (`aria-hidden`): the host pager (PostCarousel, ProfileCarousel, a media gallery) tracks the active index — typically via IntersectionObserver on its snap targets — and passes it down; tapping a dot does not navigate. Renders nothing when `count` < 2 — a one-page pager has no position to indicate.",
   "element": "span",
   "props": {
     "count": {
@@ -19,7 +19,7 @@
   "slots": {
     "dot": {
       "required": true,
-      "description": "One per page. 6 × 6 (`ref.space.75`), `sys.radius.full`. Active paints `sys.color.onSurface`; inactive paints `sys.color.outlineVariant`.",
+      "description": "One per page. 6 × 6 (`ref.space.75`), `sys.radius.full`. Active paints `sys.color.text.default`; inactive paints `sys.color.border.default`.",
       "intrinsic": true
     }
   },
@@ -31,8 +31,8 @@
     "dotRadius": "sys.radius.full"
   },
   "appearance": {
-    "activeDot": "sys.color.onSurface",
-    "inactiveDot": "sys.color.outlineVariant"
+    "activeDot": "sys.color.text.default",
+    "inactiveDot": "sys.color.border.default"
   },
   "states": {
     "default": { "note": "Pagination carries no lifecycle states — the active index is its visual state, and the dots are non-interactive." }
@@ -45,7 +45,7 @@
   },
   "forbidden": [
     "Dots rendered as interactive controls (button / link, tap-to-navigate) — that needs a focusable, labelled tab-like contract this family deliberately does not carry; if navigation chrome is required, use a different component",
-    "Active dot painted with a chromatic primary / accent / brand tone — the indicator is position chrome, not emphasis; active is `sys.color.onSurface`, full stop",
+    "Active dot painted with a chromatic primary / accent / brand tone — the indicator is position chrome, not emphasis; active is `sys.color.text.default`, full stop",
     "Pagination used as a step / completion indicator for a linear task — that role is `progress`",
     "Numeric page labels, counters, or arrows composed into the row — the family is the dot row only; numbered pagination is a different pattern",
     "Rendering the row for a single page (`count` < 2) by bypassing the built-in guard — a one-page pager has no position to indicate",

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

@@ -30,9 +30,7 @@ import { ProfileHeader } from '@teamblind-chorus/ui';
 />
 ```
 
-## Use cases
-
-### Following
+## Following
 
 Active state — the trailing button has flipped to `Following` (`surfaceContainerHigh` + hairline outline) so the followed state recedes.
 
@@ -51,7 +49,7 @@ import { ProfileHeader } from '@teamblind-chorus/ui';
 />
 ```
 
-### Private
+## Private
 
 Private visibility — paints the [LockIcon](../../icons/svg/Lock.svg) on the meta row in place of the globe. Reach for it when the entity is gated (members-only channel, locked company channel).
 
@@ -69,7 +67,7 @@ import { ProfileHeader } from '@teamblind-chorus/ui';
 />
 ```
 
-### With cover image
+## Cover image
 
 A custom cover photo overrides the placeholder. The image is `object-fit: cover` — aspect ratio preserved, cropped to fill the `375 / 120` cover band (scales with the host column).
 
@@ -87,7 +85,7 @@ import { ProfileHeader } from '@teamblind-chorus/ui';
 />
 ```
 
-### With status bar
+## Status bar
 
 An edge-to-edge / immersive screen — `statusBar` paints an iOS-style app status bar (time + cellular / Wi-Fi / battery) above the overlay nav, at the very top of the cover. Its fill is transparent so the cover image shows through the OS-chrome zone; the glyphs are fixed white, matching the overlay nav. Reach for it when the route renders the cover full-bleed under a translucent system status bar.
 
@@ -116,8 +114,8 @@ import { ProfileHeader } from '@teamblind-chorus/ui';
 - **identity** — vertical column under the cover. Pays `sys.layout.container.md` (16px) inline / block-end padding, no block-start padding (the action row's avatar lifts into the cover from y=0). `sys.layout.stack.xs` (8px) stack gap between the action row and the heading sub-group.
 - **actionRow** — top row of the identity column. Avatar leads (overlapping the cover); follow [Toggle Button](../button/toggle.md) trails. The toggle sits `sys.layout.stack.md` (16px) below the cover bottom — independent of the avatar's lower edge — so it reads with its own breathing room.
 - **heading** — sub-group bundling the name and meta row at `sys.layout.stack.2xs` (4px) gap. Sits below the action row.
-- **name** — entity name. `<h1>` at `sys.typo.heading.lg` (24 / Semibold) / `sys.color.onSurface`. Single line; truncates with ellipsis.
-- **meta** — visibility + follower row. `[visibility icon] [visibility label] · [followers]` in `sys.typo.body.sm` / `sys.color.onSurfaceVariant`. Single line.
+- **name** — entity name. `<h1>` at `sys.typo.heading.lg` (24 / Semibold) / `sys.color.text.default`. Single line; truncates with ellipsis.
+- **meta** — visibility + follower row. `[visibility icon] [visibility label] · [followers]` in `sys.typo.body.sm` / `sys.color.text.subtle`. Single line.
 - **followAction** — trailing [Toggle Button](../button/toggle.md) (`variant={'toggle'}`). `Follow` (inactive) → `Following` (active). Intrinsic width.
 
 ## Anatomy
@@ -132,9 +130,9 @@ import { ProfileHeader } from '@teamblind-chorus/ui';
 | identity      | Flex column, `padding-block: 0 sys.layout.container.md`, `padding-inline: sys.layout.container.md`, `sys.layout.stack.xs` (8) gap |
 | actionRow     | Flex row, `space-between` justify, `flex-start` align; follow button carries `margin-top: sys.layout.stack.md` (16) so it sits 16px below cover bottom |
 | heading       | Flex column, `sys.layout.stack.2xs` (4) gap between name and meta |
-| name          | `<h1>`, `sys.typo.heading.lg` (24 / Semibold), `sys.color.onSurface`, single-line ellipsis |
-| meta          | Flex row, `sys.layout.inline.sm` (4) gap, `sys.typo.body.sm` / Regular, `sys.color.onSurfaceVariant`; `·` separator before followers |
-| meta icon     | `sys.icon.md` (16 × 16), `sys.color.onSurfaceVariant` |
+| name          | `<h1>`, `sys.typo.heading.lg` (24 / Semibold), `sys.color.text.default`, single-line ellipsis |
+| meta          | Flex row, `sys.layout.inline.sm` (4) gap, `sys.typo.body.sm` / Regular, `sys.color.text.subtle`; `·` separator before followers |
+| meta icon     | `sys.icon.md` (16 × 16), `sys.color.text.subtle` |
 | followAction  | [Toggle Button](../button/toggle.md) (Toolbar-Button footprint); state tokens delegate to Toggle Button |
 
 ## States