@teamblind-chorus/ui 1.0.0

package/agents/components/form-field/select.md

@@ -0,0 +1,101 @@
+# Select
+
+Input-shaped picker — same box, label, helper, and error re-tone as [Input](./input.md), but read-only and ending in an `ArrowDownIcon` chevron. Clicking opens a Bottom Sheet with the option list; chosen value is echoed back through `value`.
+
+**Reach for this when** the user picks one value from a known set that's too long for inline chips — country, currency, sort order, equity tier. **Skip when** the value is free text ([Input](./input.md)), the user searches an open set ([Search bar](./search.md)), or the list is short enough to surface inline as a [Radio list](../list/radio.md).
+
+**Layout inset.** `inline` — ships no padding outside its own box chrome. Sits inside the host form column (settings page, Dialog body, BottomSheet form group) with the host paying surrounding stack rhythm and inline padding. Inside a bounded surface (Card / Dialog / BottomSheet / Sheet), the host already owns the inset — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+Neutral at-rest field — transparent fill, hairline `outlineVariant` stroke, placeholder in faint `outline` colour. The trailing 16px chevron signals that the field opens a sheet rather than a caret.
+
+```preview
+form-field/select/default
+---
+import { FormField } from '@teamblind-chorus/ui';
+
+<FormField variant="select" placeholder="Select an option" onOpen={() => {}} />
+```
+
+## Use cases
+
+### With leading icon
+
+Optional `leadingIcon` (16px / `sys.icon.md`) pins inner-left — same affordance as Search bar's glyph. Available on `input` and `select`.
+
+```preview
+form-field/select/with-leading-icon
+---
+import { FormField } from '@teamblind-chorus/ui';
+import { GlobeIcon } from '@teamblind-chorus/ui/icons';
+
+<FormField
+  variant="select"
+  label="Country"
+  leadingIcon={<GlobeIcon />}
+  placeholder="Choose country"
+/>
+```
+
+### Group
+
+Pair a Select with an Input on one row via `<FormFieldGroup direction="horizontal">`. The group owns one shared label above and helper below; children render as bare boxes joined at `sys.layout.inline.md` gap. Typical pattern: leading Select (country dial code, currency, unit) + trailing real Input.
+
+```preview
+form-field/select/group
+---
+import { FormField, FormFieldGroup } from '@teamblind-chorus/ui';
+
+<FormFieldGroup direction="horizontal" label="Phone number" helper="We'll text a one-time code">
+  <FormField variant="select" value="+82" onOpen={() => {}} style={{ flex: '0 0 96px' }} />
+  <FormField variant="input" placeholder="010-0000-0000" />
+</FormFieldGroup>
+```
+
+### Focus indicator
+
+Same as [Input → Focus indicator](./input.md#focus-indicator) — layered on top of the `active` border re-tone.
+
+```preview
+form-field/select/focused
+---
+import { FormField } from '@teamblind-chorus/ui';
+
+<FormField
+  variant="select"
+  placeholder="Select an option"
+  state="focused"
+  onOpen={() => {}}
+/>
+```
+
+## Appearance
+
+Same two-appearance axis as [Input → Appearance](./input.md#appearance) — `default` and `error`. The error re-tone covers box, chevron, label and helper rung; placeholder text steps to `onErrorContainer`.
+
+## Slots
+
+- **container** — same as [Input → Slots](./input.md#slots). Read-only.
+- **leading** *(optional)* — 16px decorative glyph at the inner-left edge.
+- **input** — read-only echo of the picked value (or placeholder when empty). Not editable.
+- **dropdown** — trailing `ArrowDownIcon` chevron (16px / `sys.icon.md`). Always present; clicking it fires `onOpen` (so does parent box click).
+- **label** *(optional)* / **helper** *(optional)* — same anatomy as Input. `count` is **not** offered (read-only field has nothing to count).
+
+## Sizes
+
+Identical footprint to [Input → Sizes](./input.md#sizes) — 40px tall, `sys.radius.md` corners, hairline rest stroke, thin active stroke as inset `box-shadow`. The trailing chevron occupies the slot Input reserves for clear.
+
+## States
+
+Same five states as [Input → States](./input.md#states). `active` is reached by clicking the field (the sheet then takes over) rather than by a caret.
+
+## Focus indicator
+
+Same composition as [Input → Focus indicator](./input.md#focus-indicator). Suppressed while `disabled`. Trigger: `:focus-visible`.
+
+## Behavior
+
+- **Read-only.** Does not accept keystrokes — `value` is set by the consumer when a sheet option is picked.
+- **Open on click.** Clicking the box (or the chevron) fires `onOpen`. The consumer owns the `BottomSheet` state and the option list (typically a [Radio list](../list/radio.md)); on pick, closes the sheet and updates `value`. The docs preview shows the field at rest only.
+- **No clear button.** Trailing slot is the chevron; clearing is done by the sheet's option list.

package/agents/components/form-field/select.spec.json

@@ -0,0 +1,194 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "FormField",
+  "family": "form-field",
+  "subcomponent": "select",
+  "exportAlias": "Select",
+  "description": "Input-shaped picker — the same transparent-fill box, hairline-at-rest / thin-at-active inset box-shadow stroke, label / helper rungs and `error` re-tone as Input, but the field is read-only and the trailing slot carries a `ArrowDownIcon` chevron (16px / `sys.icon.md`). Clicking anywhere in the box fires `onOpen`, and the consumer raises a `BottomSheet` (or other surface) with the option list. The chosen value is echoed back through `value`. Supports an optional leading icon, sized to `sys.icon.md`, that pins at the inner-left edge — same affordance as Search bar's glyph.",
+  "element": "div",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "select"
+    },
+    "appearance": {
+      "type": "enum",
+      "values": [
+        "default",
+        "error"
+      ],
+      "default": "default"
+    },
+    "value": {
+      "type": "string",
+      "optional": true
+    },
+    "defaultValue": {
+      "type": "string",
+      "optional": true
+    },
+    "placeholder": {
+      "type": "string",
+      "optional": true
+    },
+    "label": {
+      "type": "node",
+      "optional": true
+    },
+    "helper": {
+      "type": "node",
+      "optional": true
+    },
+    "leadingIcon": {
+      "type": "node",
+      "optional": true,
+      "description": "Optional 16px (`sys.icon.md`) decorative glyph pinned at the inner-left edge of the field. Tracks the field's active text colour (`sys.color.onSurface` on the default appearance, `sys.color.onErrorContainer` on `error`) so the glyph reads as part of the typed content."
+    },
+    "onOpen": {
+      "type": "function",
+      "optional": true,
+      "description": "Fired when the field box or the trailing chevron is clicked. Consumers use this to raise a `BottomSheet` with the option list."
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "intrinsic": true,
+      "description": "The box — same as Input."
+    },
+    "leading": {
+      "required": false,
+      "description": "Optional 16px glyph at the inner-left edge. Decorative (`aria-hidden`).",
+      "accepts": [
+        "icon"
+      ]
+    },
+    "input": {
+      "required": true,
+      "description": "Read-only echo of the selected value (or the placeholder when empty).",
+      "accepts": [
+        "text"
+      ]
+    },
+    "dropdown": {
+      "required": true,
+      "intrinsic": true,
+      "description": "Trailing chevron button (`ArrowDownIcon`, 16px). Always present, fires `onOpen`."
+    },
+    "label": {
+      "required": false,
+      "accepts": [
+        "text"
+      ]
+    },
+    "helper": {
+      "required": false,
+      "accepts": [
+        "text"
+      ]
+    }
+  },
+  "sizing": {
+    "minHeight": "ref.space.500",
+    "paddingBlock": "sys.layout.container.xs",
+    "paddingInline": "sys.layout.container.sm",
+    "slotGap": "sys.layout.inline.md",
+    "radius": "sys.radius.md",
+    "borderWidth": "sys.borderWidth.hairline",
+    "activeStrokeWeight": "sys.borderWidth.thin",
+    "groupGap": "sys.layout.stack.xs",
+    "labelTypo": "sys.typo.label.md",
+    "helperTypo": "sys.typo.body.sm",
+    "countTypo": "sys.typo.body.sm",
+    "countCurrentTypo": "sys.typo.label.md",
+    "textTypo": "sys.typo.body.md",
+    "iconSize": "sys.icon.md"
+  },
+  "groupColors": {
+    "label": "sys.color.onSurface",
+    "helper": "sys.color.onSurfaceVariant",
+    "helperError": "sys.color.error",
+    "count": "sys.color.onSurfaceVariant",
+    "countCurrent": "sys.color.onSurface"
+  },
+  "appearances": {
+    "default": {
+      "background": "transparent",
+      "text": "sys.color.onSurface",
+      "placeholder": "sys.color.outline",
+      "borderRest": "sys.color.outlineVariant",
+      "borderHover": "sys.color.outline",
+      "borderActive": "sys.color.onSurface"
+    },
+    "error": {
+      "background": "sys.color.errorContainer",
+      "text": "sys.color.onErrorContainer",
+      "placeholder": "sys.color.onErrorContainer",
+      "borderRest": "sys.color.error",
+      "borderHover": "sys.color.error",
+      "borderActive": "sys.color.error"
+    }
+  },
+  "states": {
+    "default": {
+      "overlay": null,
+      "border": "borderRest"
+    },
+    "hovered": {
+      "overlay": null,
+      "border": "borderHover"
+    },
+    "pressed": {
+      "border": "borderHover",
+      "overlay": {
+        "color": "text",
+        "opacity": "sys.state.pressed"
+      }
+    },
+    "active": {
+      "overlay": null,
+      "border": "borderActive",
+      "strokeWeight": "activeStrokeWeight"
+    },
+    "disabled": {
+      "overlay": null,
+      "background": "sys.color.surfaceContainerLow",
+      "containerOpacity": "sys.state.disabled",
+      "suppressFocusRing": true,
+      "cursor": "not-allowed"
+    }
+  },
+  "focusIndicator": {
+    "description": "Same keyboard-focus indicator as Input — outward two-layer ring composed over the active stroke.",
+    "composition": "outward",
+    "compositionReason": "Action affordance with breathing room around it.",
+    "overlay": {
+      "color": "label",
+      "opacity": "sys.state.focus"
+    },
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset"
+    },
+    "trigger": ":focus-visible"
+  },
+  "accessibility": {
+    "role": "the field box is the combobox trigger: role='combobox' with aria-haspopup='listbox' (the raised BottomSheet hosts the option list as a listbox) and aria-expanded reflecting whether the popup is open. aria-controls points at the popup list's id while open. Mirrors the dropdown-trigger contract already defined on button/text (aria-haspopup / aria-expanded / aria-controls).",
+    "focusable": "Because the element is a `div`, it MUST carry tabindex='0' so it is reachable in the tab order — without it the picker is keyboard-inoperable.",
+    "keyboard": "Enter, Space, and ArrowDown all fire onOpen (open the option surface) when the field is focused — a keyboard user must be able to open the picker without a pointer. Esc closes the raised surface (owned by the BottomSheet).",
+    "labelling": "aria-labelledby points at the label when one is composed; otherwise the consumer supplies an aria-label. aria-describedby points at the helper when rendered.",
+    "invalid": "On the `error` appearance the trigger carries aria-invalid='true', cleared when the appearance returns to default — same contract as Input.",
+    "leadingIconDecorative": "The leading glyph is aria-hidden (see the leading slot)."
+  },
+  "forbidden": [
+    "select rendered as a raw <select> — select variant wraps the native control with the chorus-field chrome",
+    "trailing chevron omitted — select always carries the trailing chevron in the rest state",
+    "select trigger that is not keyboard-focusable / openable — the div MUST carry tabindex='0' and open on Enter / Space / ArrowDown; a pointer-only picker is forbidden"
+  ]
+}

package/agents/components/form-field/textarea.md

@@ -0,0 +1,89 @@
+# Textarea
+
+Multi-line cousin of [input](./input.md) — identical chrome contract (transparent fill, inset box-shadow stroke, optional `label` / `helper` / `maxLength` group rungs); the inner element is a `<textarea>` with configurable `rows` (default 4) and vertical-only resize.
+
+**Reach for this when** the value naturally spans multiple lines: compose surfaces, bug reports, profile bios, comment composers. **Skip when** the value is single-line ([input](./input.md)), needs a leading magnifier glyph ([search](./search.md)), or opens a sheet-driven option list ([select](./select.md)).
+
+**Layout inset.** `inline` — ships no padding outside its own box chrome. Sits inside the host form column (settings page, Dialog body, BottomSheet compose surface) with the host paying surrounding stack rhythm and inline padding. Inside a bounded surface (Card / Dialog / BottomSheet / Sheet), the host already owns the inset — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+Labeled multi-line field with helper text. Four rows tall by default; the user drags the bottom-right resize handle to grow taller.
+
+```preview
+form-field/textarea
+---
+import { FormField } from '@teamblind-chorus/ui';
+
+<FormField
+  variant="textarea"
+  label="Description"
+  placeholder="Add a description for your channel"
+  helper="Up to 280 characters. Markdown is supported."
+/>
+```
+
+## Use cases
+
+### Error appearance
+
+`appearance="error"` re-tones container to `errorContainer` and stroke to `error`. The optional `helper` paints in `sys.color.error` as the error caption.
+
+```preview
+form-field/textarea-error
+---
+import { FormField } from '@teamblind-chorus/ui';
+
+<FormField
+  variant="textarea"
+  label="Description"
+  defaultValue=""
+  appearance="error"
+  helper="Description is required."
+/>
+```
+
+### With character count
+
+`maxLength` caps value length and renders a `current/max` count below the box (right-aligned). Mutually exclusive with `helper` — count wins.
+
+```preview
+form-field/textarea-count
+---
+import { FormField } from '@teamblind-chorus/ui';
+
+<FormField
+  variant="textarea"
+  label="Bio"
+  defaultValue="Designing for clarity, building for trust."
+  maxLength={140}
+  rows={3}
+/>
+```
+
+## Slots
+
+Delegates to the family group anatomy. Single divergence vs [input](./input.md) is the inner element:
+
+- **textarea** — multi-line editable text. `body.md` typo, `resize: vertical`, `rows` minimum. No trailing clear (multi-line content is too costly to wipe in one click).
+
+See [input.md § Slots](./input.md#slots) for shared label / container / helper / count slots.
+
+## Anatomy
+
+| Slot      | Token bindings |
+|-----------|----------------|
+| group     | Same as [input.md § Anatomy](./input.md#anatomy) |
+| label     | Same as input |
+| container | Same chrome; `align-items: stretch` so the textarea fills the box height |
+| textarea  | `sys.typo.body.md`, `resize: vertical`, `rows` floor (default 4) |
+| helper    | Same as input |
+| count     | Same as input |
+
+## Behavior
+
+- **`rows` floor.** At least `rows` tall (default 4). Drag the bottom-right handle to grow.
+- **Vertical resize only.** `resize: vertical` — horizontal resize breaks the parent column's rhythm and is forbidden.
+- **No clear button.** Multi-line content is too costly to wipe in one click. Users clear by selecting and deleting.
+- **`maxLength` precedence.** When both `helper` and `maxLength` are supplied, count wins and `helper` is ignored. Pick one per field.
+- **Disabled state.** Same as input — `sys.color.surfaceContainerLow` background at `sys.state.disabled` opacity, `cursor: not-allowed`.

package/agents/components/form-field/textarea.spec.json

@@ -0,0 +1,176 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "FormField",
+  "family": "form-field",
+  "subcomponent": "textarea",
+  "exportAlias": "Textarea",
+  "description": "Multi-line text field. Identical chrome contract to [input](./input.md) — transparent-fill box whose visible stroke is an inset box-shadow (never a `border`, so the field's footprint is pixel-stable across every state), 16px text in `body.md`, optional `label` above and `helper` / `maxLength` below. Diverges only on the inner element: a `<textarea>` instead of a single-line `<input>`, with a configurable `rows` rung (default 4) and a vertical-only resize handle. Same `label` / `helper` / `maxLength` group rules as input — multi-line + character count is the canonical Chorus pairing for any composition field that bounds the message length.",
+  "element": "textarea",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "textarea"
+    },
+    "appearance": {
+      "type": "enum",
+      "values": ["default", "error"],
+      "default": "default"
+    },
+    "value": {
+      "type": "string",
+      "optional": true
+    },
+    "defaultValue": {
+      "type": "string",
+      "optional": true
+    },
+    "placeholder": {
+      "type": "string",
+      "optional": true
+    },
+    "label": {
+      "type": "node",
+      "optional": true,
+      "description": "Visible label rendered above the field box and associated with it (`<label htmlFor>`)."
+    },
+    "helper": {
+      "type": "node",
+      "optional": true,
+      "description": "Assistive text rendered below the field box, left-aligned. Same rules as [input.helper](./input.md): mutually exclusive with `maxLength`, optional on every appearance, re-tones to `sys.color.error` on the error appearance."
+    },
+    "maxLength": {
+      "type": "number",
+      "optional": true,
+      "description": "Caps the value length and renders a `current/max` character count below the box, right-aligned. Mutually exclusive with `helper`."
+    },
+    "rows": {
+      "type": "number",
+      "default": 4,
+      "description": "Minimum visible rows. The textarea is `resize: vertical` so the user can pull it taller; the value never shrinks below `rows`."
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "slots": {
+    "group": {
+      "required": false,
+      "description": "Wrapper around the label + box + helper/count, present only when at least one of `label` / `helper` / `maxLength` is supplied. Delegates to the input/textarea-shared group spec.",
+      "intrinsic": true
+    },
+    "label": {
+      "required": false,
+      "description": "Visible label above the box. `sys.typo.label.md`, `sys.color.onSurface`. Associated with the textarea via `htmlFor`.",
+      "accepts": ["text"]
+    },
+    "container": {
+      "required": true,
+      "description": "The box — owns the transparent fill, the stroke (an inset box-shadow), radius, padding, focus ring. Same chrome as input; differs only in `align-items: stretch` so the inner textarea fills the box height.",
+      "intrinsic": true
+    },
+    "textarea": {
+      "required": true,
+      "description": "The editable multi-line text. `body.md` typo, `resize: vertical`, `rows` minimum. Carries `aria-describedby` pointing at the helper / count when present. No trailing clear button — the value can be long enough that wiping it via a single click is hostile; the user clears multi-line content by selecting text.",
+      "accepts": ["text"]
+    },
+    "helper": {
+      "required": false,
+      "description": "Assistive text below the box. Same rules as input.helper.",
+      "accepts": ["text"]
+    },
+    "count": {
+      "required": false,
+      "description": "`current/max` character count below the box, right-aligned. Same rules as input.count.",
+      "accepts": ["text"]
+    }
+  },
+  "sizing": {
+    "minHeight": "ref.space.500",
+    "paddingBlock": "sys.layout.container.xs",
+    "paddingInline": "sys.layout.container.sm",
+    "slotGap": "sys.layout.inline.md",
+    "radius": "sys.radius.md",
+    "borderWidth": "sys.borderWidth.hairline",
+    "activeStrokeWeight": "sys.borderWidth.thin",
+    "groupGap": "sys.layout.stack.xs",
+    "labelTypo": "sys.typo.label.md",
+    "helperTypo": "sys.typo.body.sm",
+    "countTypo": "sys.typo.body.sm",
+    "countCurrentTypo": "sys.typo.label.md",
+    "textTypo": "sys.typo.body.md",
+    "iconSize": "sys.icon.md",
+    "rowsDefault": 4,
+    "resize": "vertical"
+  },
+  "groupColors": {
+    "label": "sys.color.onSurface",
+    "helper": "sys.color.onSurfaceVariant",
+    "helperError": "sys.color.error",
+    "count": "sys.color.onSurfaceVariant",
+    "countCurrent": "sys.color.onSurface"
+  },
+  "appearances": {
+    "default": {
+      "background": "transparent",
+      "text": "sys.color.onSurface",
+      "placeholder": "sys.color.outline",
+      "borderRest": "sys.color.outlineVariant",
+      "borderHover": "sys.color.outline",
+      "borderActive": "sys.color.onSurface"
+    },
+    "error": {
+      "background": "sys.color.errorContainer",
+      "text": "sys.color.onErrorContainer",
+      "placeholder": "sys.color.onErrorContainer",
+      "borderRest": "sys.color.error",
+      "borderHover": "sys.color.error",
+      "borderActive": "sys.color.error"
+    }
+  },
+  "states": {
+    "default": { "overlay": null, "border": "borderRest" },
+    "hovered": { "overlay": null, "border": "borderHover" },
+    "pressed": {
+      "border": "borderHover",
+      "overlay": { "color": "text", "opacity": "sys.state.pressed" }
+    },
+    "active": {
+      "overlay": null,
+      "border": "borderActive",
+      "strokeWeight": "activeStrokeWeight",
+      "caret": "visible",
+      "note": "Stroke steps from `hairline` (1px) to `activeStrokeWeight` (2px) as an inset box-shadow — same pixel-stable contract as input."
+    },
+    "disabled": {
+      "overlay": null,
+      "background": "sys.color.surfaceContainerLow",
+      "containerOpacity": "sys.state.disabled",
+      "suppressFocusRing": true,
+      "cursor": "not-allowed"
+    }
+  },
+  "focusIndicator": {
+    "description": "Same outward 3-layer ring as input.focusIndicator.",
+    "composition": "outward",
+    "compositionReason": "Action affordance with breathing room around it; the 3px outward extent is reserved by the surrounding layout.",
+    "overlay": {
+      "color": "label",
+      "opacity": "sys.state.focus"
+    },
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset"
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "forbidden": [
+    "raw <textarea> styled with Tailwind / inline color — the textarea is wrapped in the chorus-field chrome that owns the stroke",
+    "auto-grow without bounds — the textarea has a `rows` floor; tall content is reachable by the user via the resize handle, not by an uncapped programmatic grow",
+    "horizontal resize handle — only the vertical handle is allowed (`resize: vertical`); horizontal resize breaks the parent column's rhythm",
+    "trailing clear button — multi-line content is too costly to wipe in one click",
+    "stroke painted via `border:` — stroke is an inset box-shadow on the field"
+  ]
+}

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

@@ -0,0 +1,43 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "header",
+  "name": "Header",
+  "description": "Labelled-header family. Two members split on the tone/weight axis: `main` (the louder member, `<Header>`) is an `onSurface` section heading at 16 / 20 that owns the See-all action, icon drill-in, and sort/filter dropdown affordances; `sub` (the quieter member, `<SubHeader>`) is a muted `onSurfaceVariant` group label at 14 that names the rows beneath it and carries at most a single Text Button action. Both are full-bleed (transparent background, own `container.md` 16 inline rail), share the heading anatomy (leading label + optional trailing affordance), and head a block of content below — `main` above a list / carousel / feed / card / sheet section, `sub` above a grouped sub-stack within an already-headed region.",
+  "useCases": [
+    "section heading",
+    "see-all link",
+    "in-sheet sub-section heading",
+    "bounded card heading",
+    "labelled block above a list / carousel / feed",
+    "quiet group label above a grouped stack of rows"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "full-bleed",
+  "wrapperGuidance": "Full-bleed: both members own their inline padding internally — `container.md` (16), the same rail the List rows / Feed items they head pay — plus asymmetric block padding (`main`: `stack.lg` 24 above / `stack.md` 16 below; `sub`: `stack.lg` 24 above / `stack.xs` 8 below). Drop the header directly above a labelled region as a sibling of the full-bleed content it heads; both land on the shared rail with no host help. Do NOT wrap it in an extra `padding-inline` div, `className=\"px-*\"`, or `style={{ padding }}`, and do NOT pay the rail again on the host — the gutter is paid once, on the header. Hosts that bundle a header above a List/Feed (DirectoryList, NavList, SideSheet column) stay full-bleed (no inline padding of their own) and absorb only the header's block padding into their stack rhythm. The transparent background means the header paints on whatever surface tier hosts it.",
+  "spec": "header.md",
+  "usage": {
+    "subs": {
+      "main": {
+        "import": "Header",
+        "example": "<Header label=\"Recommended channels\" headerAction={{ label: 'See all', href: '#all' }} />"
+      },
+      "sub": {
+        "import": "SubHeader",
+        "example": "<SubHeader label=\"Following\" />"
+      }
+    }
+  },
+  "subcomponents": [
+    {
+      "slug": "main",
+      "spec": "main.spec.json",
+      "md": "main.md",
+      "default": true
+    },
+    {
+      "slug": "sub",
+      "spec": "sub.spec.json",
+      "md": "sub.md"
+    }
+  ]
+}

package/agents/components/header/header.md

@@ -0,0 +1,18 @@
+# Header
+
+The labelled header that names a region and exposes its one highest-priority affordance. Two members share this contract and split on a **tone/weight axis**: **[Main](./main.md)** (`<Header>`) — the louder `onSurface` section heading at 16 / 20 that owns the See-all action, the icon drill-in, and the sort/filter dropdown — and **[Sub](./sub.md)** (`<SubHeader>`) — the quieter muted `onSurfaceVariant` group label at 14 that names the rows beneath it and carries at most a single Text Button action.
+
+**Layout inset.** `full-bleed` — both members have a transparent background and own their `container.md` (16) inline rail, so the label lands on the same rail as the List rows / Feed items it heads with no host help. Drop the header directly above the labelled region as a sibling; do **not** wrap it in a `padding-inline` / `px-*` / `style={{ padding }}` div, and do not pay the rail again on the host. A bundling host (Carousel, DirectoryList, NavList, SideSheet column) stays full-bleed and absorbs only the header's block padding into its stack rhythm. See [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Cross-sub contract
+
+- **Full-bleed, transparent.** Both members paint no fill and pay `sys.layout.container.md` (16) inline so the label aligns with the content rail beneath it. The header composes on whatever surface tier hosts it — never give it an opaque background.
+- **Asymmetric block rhythm.** `sys.layout.stack.lg` (24) above breaks from the previous region; the below padding binds the label to its block — `sys.layout.stack.md` (16) for Main, `sys.layout.stack.xs` (8) for the quieter Sub.
+- **Leading label + one trailing affordance.** A leading heading label and an optional trailing commit on opposite edges of a `space-between` row, separated by `sys.layout.inline.md` (8). The trailing affordance owns its own tap target; the wrapper is never interactive.
+- **Text Button actions are accent.** Any trailing Text Button reading as a link (`See all`, `Edit`) is `size="xsmall"`, `appearance="accent"` per the link-affordance rule.
+- **The split is tone/weight, not the presence of an action.** Both members may carry a trailing Text Button; only Main adds the icon drill-in and dropdown disclosure, because its `onSurface` heading earns the heavier affordance set.
+
+## Sub-components
+
+- **[Main](./main.md)** (`<Header>`) — Louder section heading. Label in `onSurface` at `typo.heading.md` (20 / Semibold, `size="large"`) or `typo.heading.sm` (16 / Semibold, `size="medium"`); trailing affordance is a See-all Text Button, an icon drill-in chevron, or a sort/filter dropdown (mutually exclusive). The canonical heading above a list / carousel / feed / card / sheet section.
+- **[Sub](./sub.md)** (`<SubHeader>`) — Quieter group label. A single muted `onSurfaceVariant` line at `typo.label.md` (14 / Semibold), no size axis; carries at most one trailing Text Button action. Names a group of rows within an already-headed region ("Following", "More Topics to follow").