@teamblind-chorus/ui 1.0.0

package/agents/components/profile-header/profile-header.family.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "profile-header",
+  "name": "ProfileHeader",
+  "description": "Identity block at the top of a profile detail screen — a full-bleed cover band, an overlapping circular [Thumbnail](../thumbnail/thumbnail.md) avatar, an entity name + visibility/follower meta row, and a trailing follow [Toggle Button](../button/toggle.md). Same 'profile' contract as [Profile carousel](../carousel/profile.md) (channel, user, company) — the carousel surfaces a fixed-shape card in a curated rail; the header is the page-level identity rung the rail's `See all` lands on. Composes under a transparent overlay [Navigation bar](../navigation-bar/sub.md) when the screen is a drill-in route.",
+  "useCases": [
+    "channel detail header",
+    "profile detail header",
+    "company channel detail header",
+    "follow / following on a profile page",
+    "cover + avatar identity block"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "full-bleed",
+  "wrapperGuidance": "Owns its inline padding internally on the meta row, and the cover band stretches edge-to-edge through the page-shell content box. Place as a direct child of the page-shell <main>. Do NOT wrap in a padding-inline div, className=\"px-*\", or style={{ padding }} — 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 — see AGENTS.md § Composition rules.",
+  "spec": "profile-header.md",
+  "usage": {
+    "note": "Paints its own overlay NavigationBar — don't wrap one yourself; opt out with nav={false}. value props are strings.",
+    "example": "<ProfileHeader name=\"…\" avatar={{ src, alt }} cover={{ src, alt }} visibility=\"public\" followers=\"…\" />"
+  },
+  "subcomponents": [
+    {
+      "slug": "profile-header",
+      "spec": "profile-header.spec.json",
+      "md": "profile-header.md",
+      "default": true
+    }
+  ]
+}

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

@@ -0,0 +1,149 @@
+# Profile header
+
+Identity block at the top of a profile detail screen — a full-bleed cover band, an overlapping circular [Thumbnail](../thumbnail/thumbnail.md) avatar, an entity name, a visibility + follower meta row, and a trailing follow [Toggle Button](../button/toggle.md). Same `profile` contract as [Profile carousel](../carousel/profile.md) (channel topic, user, company channel) — the carousel surfaces a fixed-shape card in a curated rail; the header is the page-level identity rung the rail's `See all` lands on.
+
+**Reach for this when** a profile detail route opens on a followable entity that needs a cover, an avatar, a single page-level heading, and a follow affordance. **Skip when** the screen is a feed list (use [Navigation bar/home](../navigation-bar/main.md) + [Feed](../feed/feed.md)), a settings or account drill-in (use [Navigation bar/page](../navigation-bar/sub.md) + [Nav card](../nav-card/nav-card.md)), or a curated profile rail (use [Carousel](../carousel/carousel.md) + [Profile carousel](../carousel/profile.md)).
+
+**Layout inset.** `full-bleed` — sits as a direct child of the page shell at the top of the route. The cover stretches edge-to-edge inside the page-shell content box; the identity row pays its own `16px inline / 16px block` padding via `layout.container.*`. 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).
+
+**Overlay nav.** ProfileHeader paints an overlay [Navigation bar/page](../navigation-bar/sub.md) at `appearance="overlay"` absolutely positioned at the cover's top edge — transparent fill, fixed-white icons. Defaults to a back-arrow leading and a search-icon trailing; consumer wires `onBack` / `onSearch`. Opt out with `nav={false}` when the host route owns its own top chrome.
+
+**Status bar.** Pass `statusBar` to paint an iOS-style app status bar (time + cellular / Wi-Fi / battery glyphs) above the overlay nav, at the very top of the cover — transparent fill, fixed-white glyphs, so the cover image shows through the OS-chrome zone (an edge-to-edge / immersive screen). Off by default; pass `statusBar={{ time: '…' }}` to override the canonical 9:41.
+
+## Default
+
+A public channel topic with a cover photo, a circular avatar, the entity name, and a `Follow` toggle.
+
+```preview
+profile-header/default
+---
+import { ProfileHeader } from '@teamblind-chorus/ui';
+
+<ProfileHeader
+  name="General Topic"
+  avatar={{ src: '/placeholder.png', alt: 'General Topic' }}
+  cover={{ src: 'https://images.unsplash.com/photo-1497436072909-60f360e1d4b1?w=640&h=200&fit=crop&auto=format&q=80', alt: 'Forest skyline at dusk' }}
+  visibility="public"
+  followers="999 followers"
+/>
+```
+
+## Use cases
+
+### Following
+
+Active state — the trailing button has flipped to `Following` (`surfaceContainerHigh` + hairline outline) so the followed state recedes.
+
+```preview
+profile-header/following
+---
+import { ProfileHeader } from '@teamblind-chorus/ui';
+
+<ProfileHeader
+  name="Plant People"
+  avatar={{ src: '/placeholder.png', alt: 'Plant People' }}
+  cover={{ src: 'https://images.unsplash.com/photo-1463320726281-696a485928c7?w=640&h=200&fit=crop&auto=format&q=80', alt: 'Sunlit greenhouse foliage' }}
+  visibility="public"
+  followers="21.7K followers"
+  followed
+/>
+```
+
+### 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).
+
+```preview
+profile-header/private
+---
+import { ProfileHeader } from '@teamblind-chorus/ui';
+
+<ProfileHeader
+  name="Compensation"
+  avatar={{ src: '/placeholder.png', alt: 'Compensation' }}
+  cover={{ src: 'https://images.unsplash.com/photo-1554224155-6726b3ff858f?w=640&h=200&fit=crop&auto=format&q=80', alt: 'Offer letters on a desk' }}
+  visibility="private"
+  followers="8.1K followers"
+/>
+```
+
+### With 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).
+
+```preview
+profile-header/with-cover
+---
+import { ProfileHeader } from '@teamblind-chorus/ui';
+
+<ProfileHeader
+  name="Sourdough Bakers"
+  avatar={{ src: '/placeholder.png', alt: 'Sourdough Bakers' }}
+  cover={{ src: 'https://images.unsplash.com/photo-1509440159596-0249088772ff?w=640&auto=format&q=80', alt: 'Sliced loaf with open crumb' }}
+  visibility="public"
+  followers="12.4K followers"
+/>
+```
+
+### With 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.
+
+```preview
+profile-header/with-status-bar
+---
+import { ProfileHeader } from '@teamblind-chorus/ui';
+
+<ProfileHeader
+  name="General Topic"
+  avatar={{ src: '/placeholder.png', alt: 'General Topic' }}
+  cover={{ src: 'https://images.unsplash.com/photo-1497436072909-60f360e1d4b1?w=640&h=200&fit=crop&auto=format&q=80', alt: 'Forest skyline at dusk' }}
+  visibility="public"
+  followers="999 followers"
+  statusBar
+/>
+```
+
+## Slots
+
+- **container** — outer `<section>`. Vertical stack: cover band above, identity column below. `sys.color.surface` fill; no outer padding.
+- **cover** — full-bleed image band at the top; `aspect-ratio: 375 / 120` (mobile screen-width / cover-band proportion — scales with the host column). Image-area slot (same contract as [Thumbnail](../thumbnail/thumbnail.md) and [Profile carousel](../carousel/profile.md) cover) — falls back to `/placeholder.png` over a `surfaceContainerHigh` underlay when no `cover.src` is supplied. Hosts the overlay nav at its top edge.
+- **nav** *(optional)* — [Navigation bar/page](../navigation-bar/sub.md) at `appearance="overlay"`. Absolutely positioned at the cover's top edge; transparent fill, fixed-white icons (back chevron leading, search trailing by default). Pays its own `env(safe-area-inset-top)`. Pass `nav={false}` to opt out.
+- **statusBar** *(optional)* — iOS-style app status bar (time + cellular / Wi-Fi / battery glyphs) stacked above the nav at the cover's top edge. Transparent fill, fixed-white (`ref.palette.white.1000`) glyphs — the cover image shows through. Pays its own `env(safe-area-inset-top)` (and collapses the nav's, so the two never double-inset). Decorative OS-chrome (`aria-hidden`), intentionally off-token — raw px + `-apple-system` font. Off by default; pass `statusBar` (canonical 9:41) or `statusBar={{ time }}`.
+- **avatar** — [Thumbnail](../thumbnail/thumbnail.md) `size={56}` with [`outlined={true}`](../thumbnail/thumbnail.md#with-surface-outline) overlapping the cover band's bottom edge by half its diameter (`margin-top: -28px`). The 2-token (`sys.borderWidth.thin`) `surface`-tone outset halo separating the circle from the cover is owned by Thumbnail's outlined case — the header forwards the prop instead of painting a halo on its own wrapper.
+- **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.
+- **followAction** — trailing [Toggle Button](../button/toggle.md) (`variant={'toggle'}`). `Follow` (inactive) → `Following` (active). Intrinsic width.
+
+## Anatomy
+
+| Slot          | Token bindings |
+|---------------|----------------|
+| container     | `sys.color.surface` fill, full-bleed inline, vertical stack |
+| cover         | `aspect-ratio: 375 / 120` (W × H — mobile-viewport ratio; scales with the host column), `sys.color.surfaceContainerHigh` underlay, `/placeholder.png` background-image, `object-fit: cover` on the inline `<img>`; `position: relative` so the overlay nav pins to its bounds |
+| nav           | [Navigation bar/page](../navigation-bar/sub.md) `appearance="overlay"`, stacked in the overlay column `inset: 0 0 auto 0` on the cover, transparent fill, `ref.palette.white.1000` icons |
+| statusBar     | *(optional)* iOS-style app status bar above the nav in the overlay column; transparent fill, `ref.palette.white.1000` glyphs; `padding-block-start: env(safe-area-inset-top)`; off-token OS-chrome (raw px / `-apple-system`), `aria-hidden` |
+| avatar        | [Thumbnail](../thumbnail/thumbnail.md) `size={56}` `outlined`, `margin-top: -28px` (vertical centre on cover bottom edge). The 2-token surface halo is painted by Thumbnail's `outlined` case (outset `box-shadow: 0 0 0 sys.borderWidth.thin sys.color.surface`) — wrapper has no halo of its own |
+| 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` |
+| followAction  | [Toggle Button](../button/toggle.md) (Toolbar-Button footprint); state tokens delegate to Toggle Button |
+
+## States
+
+ProfileHeader itself has no lifecycle states. The trailing follow Toggle Button carries its own state per [Toggle Button](../button/toggle.md).
+
+## Behavior
+
+- **Page-level heading.** `name` renders as `<h1>` — the host route should not paint a second `<h1>` elsewhere on the page.
+- **Cover is image-area.** Missing or failed `<img>` resolves to `/placeholder.png` over `surfaceContainerHigh`. Pass `cover.src` explicitly in design-time scaffolds so the contract reads in JSX.
+- **Avatar overlap is structural.** The avatar's `margin-top: -40px` (half its diameter) lifts it so the vertical centre lands on the cover bottom edge. The follow Toggle Button carries its own `margin-top: sys.layout.stack.md` (16) so it sits 16px below the cover regardless of where the avatar lands.
+- **Follow toggle commits in place.** Tapping `Follow` flips to `Following` and stays. State is owned by the consumer via `followed` + `onFollowChange`.
+- **Overlay nav.** Defaults to an opt-in overlay [Navigation bar/page](../navigation-bar/sub.md) at `appearance="overlay"` — transparent fill, fixed-white icons. Pass `nav={false}` to opt out when the host route already paints its own top chrome.
+- **Status bar.** Pass `statusBar` to paint an iOS-style app status bar above the nav at the cover's top edge for an edge-to-edge / immersive screen — transparent fill so the cover image shows through, fixed-white glyphs. When present, the status bar pays `env(safe-area-inset-top)` and the overlay nav collapses its own so the two sit flush. Decorative (`aria-hidden`); the time defaults to 9:41 and is overridable via `statusBar={{ time }}`.

package/agents/components/profile-header/profile-header.spec.json

@@ -0,0 +1,200 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "ProfileHeader",
+  "family": "profile-header",
+  "subcomponent": "profile-header",
+  "description": "Identity block at the top of a profile detail screen — a full-bleed cover band, an overlapping 56-rung circular [Thumbnail](../thumbnail/thumbnail.md) avatar, an entity name (`heading.lg`), a visibility-icon + visibility-label · follower-count meta row, and a trailing follow [Toggle Button](../button/toggle.md). The cover bleeds edge-to-edge inside the page-shell content box; the identity row pays the standard `sys.layout.container.md` (16px) inline padding so name / meta / follow sit on the page rail.",
+  "element": "section",
+  "props": {
+    "name": {
+      "type": "string",
+      "required": true,
+      "description": "Entity name — channel topic, person, or company. Renders as the page-level `<h1>` at `sys.typo.heading.lg` / Semibold / `onSurface`. Single line; truncates with ellipsis at narrow widths."
+    },
+    "avatar": {
+      "type": "object",
+      "required": true,
+      "description": "Forwarded to [Thumbnail](../thumbnail/thumbnail.md) verbatim at `size={56}` with `outlined={true}`. Object: `{ src, alt, updateDot?, logoBadge? }`. The avatar overlaps the cover band's bottom edge by half its height; the 2-token `surface`-tone halo that separates the circle from the cover comes from Thumbnail's `outlined` case (see [Thumbnail § With surface outline](../thumbnail/thumbnail.md#with-surface-outline))."
+    },
+    "cover": {
+      "type": "object",
+      "optional": true,
+      "description": "{ src?, alt? } — image-area override for the cover band. `src` accepts any URL; falls back to `/placeholder.png` (the universal Chorus image-area placeholder) when omitted. Same contract as `Thumbnail.src` / `ProfileCarousel.cover` — `object-fit: cover` preserves aspect ratio and crops to the band's intrinsic `375 / 120` ratio.",
+      "assetType": "image",
+      "placeholder": "/placeholder.png"
+    },
+    "visibility": {
+      "type": "literal",
+      "values": ["public", "private"],
+      "default": "public",
+      "description": "Visibility class. `public` paints the [GlobeIcon](../../icons/svg/Globe.svg) + the `visibilityLabel` (default 'Public'); `private` paints the [LockIcon](../../icons/svg/Lock.svg) + the `visibilityLabel` (default 'Private'). Consumers override the label text via `visibilityLabel`."
+    },
+    "visibilityLabel": {
+      "type": "string",
+      "optional": true,
+      "description": "Override the visibility label text — used for localisation (e.g. '공개' / '비공개'). When omitted, defaults to 'Public' / 'Private' based on `visibility`."
+    },
+    "followers": {
+      "type": "string",
+      "required": true,
+      "description": "Follower count line — formatted by the consumer so the unit / locale stays in their hands (e.g. '999 followers', '12.4K followers', '999 팔로워'). Paints in `sys.typo.body.sm` / `sys.color.onSurfaceVariant` to the right of a bullet separator on the meta row."
+    },
+    "followed": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether the viewer is following this entity. Drives the trailing [Toggle Button](../button/toggle.md): false → 'Follow' (primary fill); true → 'Following' (transparent fill + hairline outline so the committed state recedes against any host surface tier)."
+    },
+    "onFollowChange": {
+      "type": "function",
+      "optional": true,
+      "description": "Fires when the follow toggle commits — receives the next `followed` boolean. Consumer owns persistence."
+    },
+    "followLabel": {
+      "type": "string",
+      "optional": true,
+      "description": "Inactive follow-button label. Defaults to 'Follow'."
+    },
+    "followingLabel": {
+      "type": "string",
+      "optional": true,
+      "description": "Active follow-button label. Defaults to 'Following'."
+    },
+    "nav": {
+      "type": "boolean",
+      "default": true,
+      "description": "Whether to render the overlay [Navigation bar/page](../navigation-bar/sub.md) at the cover's top edge. Defaults to `true` (back-arrow leading + search trailing, transparent + fixed-white icons). Pass `false` when the host route already paints its own top chrome and the cover should be clean."
+    },
+    "statusBar": {
+      "type": "boolean | object",
+      "default": false,
+      "description": "Paint an iOS-style app status bar (time + cellular / Wi-Fi / battery glyphs) above the overlay nav at the cover's top edge — transparent fill, fixed-white (`ref.palette.white.1000`) glyphs, so the cover image shows through the OS-chrome zone (edge-to-edge / immersive screen). Off by default. Pass `true` for the canonical 9:41 time, or `statusBar={{ time: '…' }}` to override. Decorative OS-chrome mimicry: `aria-hidden`, intentionally off-token (raw px + `-apple-system` font). When present it pays `env(safe-area-inset-top)` and the overlay nav collapses its own inset so the two never double-stack below the notch."
+    },
+    "onBack": {
+      "type": "function",
+      "optional": true,
+      "description": "Click handler for the overlay nav's leading back chevron."
+    },
+    "onSearch": {
+      "type": "function",
+      "optional": true,
+      "description": "Click handler for the overlay nav's trailing search icon."
+    },
+    "backLabel": {
+      "type": "string",
+      "optional": true,
+      "description": "Accessible label for the overlay nav's back chevron. Defaults to 'Back'."
+    },
+    "searchLabel": {
+      "type": "string",
+      "optional": true,
+      "description": "Accessible label for the overlay nav's search icon. Defaults to 'Search'."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Outer `<section>`. Vertical stack — cover band first, identity row second. `sys.color.surface` fill; no outer padding (the cover is full-bleed; the identity row pays its own inline padding).",
+      "intrinsic": true
+    },
+    "cover": {
+      "required": true,
+      "description": "Full-bleed image band at the top — `aspect-ratio: 375 / 120` (mobile screen-width / cover-band ratio; the band scales proportionally as the host column resizes). **Image-area slot, same contract as `.chorus-thumbnail` and `.chorus-profile-carousel__cover`**: an `<img>` paints the band, falling back to the universal Chorus placeholder PNG (`/placeholder.png`) when no `cover.src` is supplied. The placeholder is *also* wired as the runtime CSS `background-image` on the band, so a missing / failed `<img>` still resolves to the placeholder rather than an empty surface tone. `object-fit: cover` preserves aspect ratio and crops to fill the band.",
+      "assetType": "image",
+      "placeholder": "/placeholder.png",
+      "intrinsic": true
+    },
+    "avatar": {
+      "required": true,
+      "description": "Circular avatar overlapping the cover band's bottom edge by half its diameter. Rendered via the [Thumbnail](../thumbnail/thumbnail.md) component at `size={56}` and `outlined={true}` — the 2-token `surface`-tone halo that separates the avatar from the cover band is owned by Thumbnail's outlined case (see [Thumbnail § With surface outline](../thumbnail/thumbnail.md#with-surface-outline)), not by the header's own wrapper. Every other Thumbnail prop is forwarded verbatim; the header does not paint its own crop or image-area fallback.",
+      "accepts": ["thumbnail"],
+      "rendersAs": "thumbnail:56"
+    },
+    "identity": {
+      "required": true,
+      "description": "Vertical column below the cover. Pays `sys.layout.container.md` (16px) inline padding and `sys.layout.stack.xs` (8px) stack gap between the action-row, the name, and the meta row.",
+      "intrinsic": true
+    },
+    "nav": {
+      "required": false,
+      "description": "Overlay [Navigation bar/page](../navigation-bar/sub.md) at `appearance=\"overlay\"` — stacked in the overlay column at the cover's top edge with a transparent fill and fixed-white icons (back chevron leading, search trailing by default). Floats over the cover image; the host wires `onBack` / `onSearch`. Opt out with `nav={false}`.",
+      "intrinsic": true,
+      "rendersAs": "navigation-bar:page (appearance='overlay')"
+    },
+    "statusBar": {
+      "required": false,
+      "description": "iOS-style app status bar (time + cellular / Wi-Fi / battery glyphs) stacked above the nav at the cover's top edge — transparent fill, fixed-white (`ref.palette.white.1000`) glyphs so the cover image shows through. Pays its own `env(safe-area-inset-top)` (and collapses the nav's so the two never double-inset). Decorative OS-chrome mimicry — `aria-hidden`, intentionally off-token (raw px + `-apple-system` font). Opt in with `statusBar` / `statusBar={{ time }}`.",
+      "intrinsic": true
+    },
+    "actionRow": {
+      "required": true,
+      "description": "Top row of the identity column. The avatar sits at the leading edge (overlapping the cover by half its diameter); the trailing [Toggle Button](../button/toggle.md) follow action sits at the trailing edge, **16px (`sys.layout.stack.md`) below the cover bottom**, so the affordance reads as its own breathing-room rather than aligning to the avatar's lower edge. `space-between` justify pins the two affordances to opposite edges.",
+      "intrinsic": true
+    },
+    "heading": {
+      "required": true,
+      "description": "Sub-group bundling the name and meta row. Vertical flex with `sys.layout.stack.2xs` (4px) gap so the page-level title and its meta line read as one heading block, set apart from the action row above by the identity column's `sys.layout.stack.xs` (8px) parent gap.",
+      "intrinsic": true
+    },
+    "name": {
+      "required": true,
+      "description": "Entity name. Renders as `<h1>` at `sys.typo.heading.lg` (24 / Semibold) / `sys.color.onSurface`. Single line; truncates with ellipsis. Sits inside the `heading` sub-group.",
+      "accepts": ["text"]
+    },
+    "meta": {
+      "required": true,
+      "description": "Visibility + follower meta row. Composed as: [visibility icon] [visibility label] [bullet separator] [follower count]. `sys.typo.body.sm` (14 / Regular) / `sys.color.onSurfaceVariant`. Single line. Sits inside the `heading` sub-group, 4px below the name.",
+      "intrinsic": true
+    },
+    "followAction": {
+      "required": true,
+      "description": "Trailing [Toggle Button](../button/toggle.md) (`variant={'toggle'}`). `Follow` (inactive — `primary` fill) ↔ `Following` (active — `transparent` fill + hairline outline so the committed state reads as a ghost outline against any host surface tier). Sits inside the action row, intrinsic width.",
+      "accepts": ["button"],
+      "rendersAs": "button:toggle"
+    }
+  },
+  "sizing": {
+    "containerFill": "sys.color.surface",
+    "coverAspectRatio": "375 / 120 (W × H — the mobile-viewport / cover-band proportion; the band scales with the host column instead of locking to a hard pixel height)",
+    "coverFill": "sys.color.surfaceContainerHigh (background underlay — the placeholder image paints on top via `object-fit: cover`)",
+    "coverImageSource": "Same `/placeholder.png` asset every Chorus image-area slot falls back to. Decorative — `aria-hidden`. Consumers override via the `cover.src` prop.",
+    "avatarSize": 56,
+    "avatarOverlap": "Avatar's vertical center sits on the cover band's bottom edge — the top half overlaps the cover, the bottom half sits on the identity surface (-28px margin-top). The 2-token `surface`-tone halo that separates the circle from the cover is owned by Thumbnail's `outlined={true}` case — see [Thumbnail § With surface outline](../thumbnail/thumbnail.md#with-surface-outline). The header does not paint a halo of its own on the wrapper; the Thumbnail's outset `box-shadow` is the contract.",
+    "identityPaddingBlock": "0 sys.layout.container.md",
+    "identityPaddingInline": "sys.layout.container.md",
+    "identityStackGap": "sys.layout.stack.xs",
+    "headingStackGap": "sys.layout.stack.2xs",
+    "actionRowAlign": "flex-start",
+    "actionRowJustify": "space-between",
+    "avatarMarginTop": "calc(-1 * 28px)",
+    "avatarMarginTopNote": "Negative margin lifts the avatar so its vertical centre lands on the cover bottom edge (half-overlap).",
+    "followMarginTop": "sys.layout.stack.md",
+    "followMarginTopNote": "Follow Toggle Button sits 16px below the cover bottom edge so the affordance reads with its own breathing room rather than aligning to the avatar's lower edge.",
+    "nameTypo": "sys.typo.heading.lg",
+    "nameColor": "sys.color.onSurface",
+    "metaTypo": "sys.typo.body.sm",
+    "metaColor": "sys.color.onSurfaceVariant",
+    "metaIconSize": "sys.icon.md",
+    "metaIconColor": "sys.color.onSurfaceVariant",
+    "metaGap": "sys.layout.inline.sm",
+    "metaSeparator": "·",
+    "followActionRendersAs": "Button variant='toggle' — Toolbar-Button footprint. State tokens delegate entirely to the Toggle Button (Chip-toggle) contract."
+  },
+  "states": {
+    "note": "ProfileHeader itself is not interactive — commit lives in the follow Toggle Button. The button follows its own spec's state contract."
+  },
+  "behavior": {
+    "coverIsImageArea": "Same image-area fallback contract as Thumbnail / Profile carousel cover: missing or failed `<img>` resolves to the bundled `/placeholder.png` over a `surfaceContainerHigh` underlay so the slot still reads as an image. Design-time scaffolds should pass `cover.src` explicitly.",
+    "avatarOverlapsCover": "Avatar carries `margin-top: -28px` so its vertical centre lands on the cover bottom edge — half-overlap (half of the 56-rung avatar). The follow Toggle Button sits in the same action row but with `margin-top: sys.layout.stack.md` (16) so it floats 16px below the cover bottom, independent of the avatar's lower edge.",
+    "followToggleCommitsInPlace": "Tapping `Follow` flips the trailing Toggle Button to `Following` and stays there. Consumer owns state via `followed` + `onFollowChange`.",
+    "nameSemantics": "`name` renders as `<h1>` — the page-level heading. The host route should not paint a separate `<h1>` elsewhere on the page. Use `as=\"div\"` on a downstream Header if a labelled-region heading is composed below.",
+    "overlayNav": "ProfileHeader paints an overlay [Navigation bar/page](../navigation-bar/sub.md) at `appearance=\"overlay\"` absolutely positioned at the cover's top edge — transparent fill, fixed-white icons, the cover image underneath provides the contrast. The bar pays its own `env(safe-area-inset-top)`. Defaults: back chevron leading, search icon trailing; consumer wires `onBack` / `onSearch`. Opt out with `nav={false}` when the host route prefers no overlay chrome.",
+    "statusBar": "Pass `statusBar` to stack an iOS-style app status bar (time + cellular / Wi-Fi / battery glyphs) above the overlay nav at the cover's top edge for an edge-to-edge / immersive screen — transparent fill so the cover image shows through, fixed-white glyphs. When present, the status bar pays `env(safe-area-inset-top)` and the overlay nav collapses its own top inset so the two sit flush in the overlay column. Decorative OS-chrome (`aria-hidden`), off-token by design. Time defaults to iOS's canonical 9:41; override via `statusBar={{ time }}`."
+  },
+  "forbidden": [
+    "ProfileHeader wrapped in a horizontal-padding div — the family is full-bleed by declaration; the identity row pays inline padding internally",
+    "cover painted as an inline SVG — cover uses /placeholder.png via the image-area contract, object-fit: cover",
+    "follow affordance rendered as a Standard Button or Text Button — Follow is the canonical Toggle Button shape; the Toolbar-Button footprint is non-negotiable",
+    "avatar rendered at a size other than 56 — the family fixes the avatar rung so the cover-overlap geometry stays consistent",
+    "second `<h1>` painted elsewhere on the host route — ProfileHeader owns the page-level heading semantics"
+  ]
+}

package/agents/components/progress/progress.family.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "progress",
+  "name": "Progress",
+  "description": "Linear progress bar — a slim horizontal track that previews how far a long-running task has advanced. Determinate only: a filled segment parks at the value's ratio. One appearance, no emphasis axis: the track paints `sys.color.scrimSubtle` (a faint inverse-tone scrim that reads on any host surface tier) and the indicator paints `sys.color.inverseSurface` so the filled segment always contrasts against the bare track in either theme. A single 8px fully-rounded rung. If a screen needs a higher-attention progress mark, the emphasis belongs in the surrounding copy (e.g. a Banner), never in a chromatic indicator tone. Single-spec family.",
+  "useCases": [
+    "upload / download progress",
+    "onboarding step progress",
+    "background sync indicator",
+    "long-running task progress on a screen header"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "inline",
+  "spec": "progress.md",
+  "usage": {
+    "note": "value is a 0–1 ratio, not a 0–100 percent. Determinate only; the label lives on the host surface.",
+    "example": "<Progress value={0.4} aria-label=\"…\" />"
+  },
+  "subcomponents": [
+    {
+      "slug": "progress",
+      "spec": "progress.spec.json",
+      "md": "progress.md",
+      "default": true
+    }
+  ]
+}

package/agents/components/progress/progress.md

@@ -0,0 +1,38 @@
+# Progress
+
+A single visual rung — 8px tall, fully rounded — that previews how far a long-running task has advanced. Determinate only: a filled indicator parks at the value's ratio. No emphasis axis: track paints with `sys.color.scrimSubtle` (the translucent inverse-tone scrim — ~8% black light, ~8% white dark); indicator paints in `inverseSurface` so the filled segment contrasts against the track regardless of theme.
+
+**Reach for this when** a screen holds a task long enough that the user would otherwise wonder if anything is happening — file uploads, onboarding step counters, background syncs, account migrations. **Skip when** the task resolves under 300ms, the wait is purely opaque (use [Skeleton](../skeleton/skeleton.md) for content placeholders, busy spinners for short opaque waits), or the metric is primary content rather than chrome (use a chart).
+
+**Layout inset.** `inline` — Progress ships no padding of its own. Stretches to fill whichever host column it sits in. Pair with a label / supporting line via the host surface, not Progress itself.
+
+## Default
+
+A determinate progress bar at 40%. 8px tall, `radius.full` corners, `inverseSurface` indicator on a Banner-style scrim track. Transitions over 200ms when `value` changes.
+
+```preview
+progress/default
+---
+import { Progress } from '@teamblind-chorus/ui';
+
+<Progress value={0.4} aria-label="Uploading file" />
+```
+
+## Slots
+
+- **track** — fully-rounded background block. 8px tall, `sys.color.scrimSubtle` fill (translucent inverse-tone scrim — black 8% light, white 8% dark), no stroke. Carries `role="progressbar"` and the aria-value attributes.
+- **indicator** *(decorative)* — inner filled segment painted in `sys.color.inverseSurface`, `translateX`'d so the trailing edge lands at the value's ratio.
+
+## Anatomy
+
+| Slot         | Token bindings |
+|--------------|----------------|
+| track        | `sys.color.scrimSubtle` fill (translucent inverse-tone scrim), `sys.radius.full`, 8px (`sys.layout.container.xs`) tall |
+| indicator    | `sys.color.inverseSurface` fill, fully rounded, `transform: translateX(…)` driven |
+| transition   | 200ms `ease-out` on indicator transform as `value` changes |
+
+## Behavior
+
+- **Determinate transition.** `value` jumps animate over 200ms `ease-out` — a 30% → 60% step reads as movement, not a pop. Under `prefers-reduced-motion: reduce`, the transition is suppressed.
+- **ARIA.** `role="progressbar"`; `aria-valuemin=0`, `aria-valuemax=100`, `aria-valuenow=<rounded percent>`.
+- **No label, size, or emphasis slot.** The label (step counter, percent, task name) lives on the host surface. The family carries a single visual rung (8px) and a single appearance (inverseSurface on a scrim track).

package/agents/components/progress/progress.spec.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Progress",
+  "family": "progress",
+  "description": "Linear progress bar. A single visual rung — 8px tall, fully rounded — that previews how far a long-running task has advanced. The track paints with `sys.color.scrimSubtle` (the Banner-style inverse-tone scrim — ~8% black in light, ~8% white in dark) so the bar reads cleanly on any host surface tier without colliding with a fixed surface-container step. The indicator paints in `sys.color.inverseSurface` so the filled segment always contrasts against the scrim track regardless of theme. The track owns no width of its own — it stretches to fill its host column. Determinate only — `role='progressbar'` with `aria-valuemin / max / now` reflects the value's ratio.",
+  "element": "div",
+  "props": {
+    "value": {
+      "type": "number",
+      "default": 0,
+      "description": "Progress value. When `max` is omitted, this is the ratio 0..1; with `max`, it is the raw count and the ratio is `value / max`. Clamped to 0..1."
+    },
+    "max": {
+      "type": "number",
+      "default": 1,
+      "description": "Upper bound for `value`. Defaults to 1 so a `value` of 0.4 reads as 40%."
+    },
+    "aria-label": {
+      "type": "string",
+      "optional": true,
+      "description": "Accessible label describing what is in progress. Required when the bar is not paired with a visible label next to it."
+    }
+  },
+  "slots": {
+    "track": {
+      "required": true,
+      "description": "Fully-rounded background block. 8px tall, `sys.color.scrimSubtle` fill (translucent inverse-tone scrim — black 8% light / white 8% dark), no stroke. Carries `role='progressbar'` and the aria-value attributes.",
+      "intrinsic": true
+    },
+    "indicator": {
+      "required": true,
+      "description": "Inner filled segment painted in `sys.color.inverseSurface`, translated horizontally so its trailing edge sits at the value's ratio.",
+      "intrinsic": true
+    }
+  },
+  "sizing": {
+    "height": "sys.layout.container.xs",
+    "trackBackground": "sys.color.scrimSubtle",
+    "trackRadius": "sys.radius.full",
+    "indicatorBackground": "sys.color.inverseSurface",
+    "indicatorRadius": "inherit",
+    "transitionDuration": "200ms",
+    "transitionTiming": "ease-out"
+  },
+  "appearances": {
+    "default": {
+      "track": "sys.color.scrimSubtle",
+      "indicator": "sys.color.inverseSurface",
+      "note": "The only appearance. Track paints `sys.color.scrimSubtle` — a faint inverse-tone scrim (~8% black light / ~8% white dark) visible against every surface tier in either theme. Indicator paints in `inverseSurface` so the filled segment always contrasts against the bare track regardless of theme. Progress has no emphasis axis; if a screen needs a higher-attention progress mark, it belongs as a Banner copy nearby, not as a chromatic indicator tone."
+    }
+  },
+  "states": {
+    "default": { "note": "Progress carries no lifecycle states — the value is its visual state." }
+  },
+  "behavior": {
+    "determinateTransition": "The indicator's transform transitions over 200ms `ease-out` as `value` changes, so jumps to higher ratios animate rather than snap. Under `prefers-reduced-motion: reduce` the transition is suppressed.",
+    "ariaContract": "Container is `role='progressbar'` with `aria-valuemin=0`, `aria-valuemax=100`, and `aria-valuenow` reflecting the rounded percent of the value's ratio."
+  },
+  "forbidden": [
+    "Progress used as a permanent zero-data placeholder — that role is `skeleton`; Progress communicates active work, not absence",
+    "Progress painted thicker than 8px — taller bars read as a UI control, not as chrome. For thick-bar metric visualisation, use a chart instead",
+    "Progress nested inside a Toast — Toast is for transient confirmations of completed actions; in-progress states belong inline on the surface that owns the work",
+    "track painted with a fixed surface-container tone (e.g. `surfaceContainerHighest`) — the track MUST be the mode-aware scrim recipe so it reads on any host surface tier",
+    "indicator painted with a chromatic primary / accent / brand tone — the family has no emphasis axis; emphasis belongs in the surrounding copy, not in the bar itself",
+    "track stroke painted with a `border:` — track is a fully-rounded block with no stroke; the affordance is the fill contrast between the scrim and the indicator"
+  ]
+}

package/agents/components/side-sheet/side-sheet.family.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "side-sheet",
+  "name": "SideSheet",
+  "description": "Off-canvas content column anchored to the leading or trailing edge of the viewport. Pairs with BottomSheet as the Sheet family's other anchor: BottomSheet for committed-sheet flows, SideSheet for off-canvas navigation columns, settings panes, channel directories, filter rails. The composition is free-form — the canonical fill is a Header (size=\"medium\") column heading + an embedded [list/entry](../list/entry.md) directory stack (40 avatar + label + inline count Badge + optional trailing icon toggle), optionally followed by another Header + List(entry) pair and a pinned footer commit.",
+  "useCases": [
+    "navigation drawer",
+    "channel directory",
+    "off-canvas filter rail",
+    "settings panel",
+    "subscription / favorites column",
+    "sub-navigation overlay"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "bounded-surface",
+  "wrapperGuidance": "Renders into a body portal — its own modal-like surface. Treat the same as BottomSheet / Dialog: do not wrap the `<SideSheet>` call in any layout container; place it as a sibling of the page shell so the portal mounts at body root. Full-bleed children inside the sheet body negate the body's inline padding via the negative-margin opt-out (see AGENTS.md § Composition rules).",
+  "spec": "side-sheet.md",
+  "usage": {
+    "note": "Portal-rendered; controlled via open/onClose. Free-form children — group canonical Header + List(entry) stacks in SideSheetGroup.",
+    "example": "<SideSheet open onClose={close} aria-label=\"…\" footer={…}><SideSheetGroup>…</SideSheetGroup></SideSheet>"
+  },
+  "subcomponents": [
+    {
+      "slug": "side-sheet",
+      "spec": "side-sheet.spec.json",
+      "md": "side-sheet.md",
+      "default": true
+    }
+  ]
+}