@teamblind-chorus/ui 1.0.0

package/agents/components/header/main.md

@@ -0,0 +1,101 @@
+# Main
+
+The louder member of the [Header](./header.md) family — a labelled `onSurface` heading + an optional trailing affordance, reached as `<Header>`. The composable header anatomy reused across [Carousel](../carousel/carousel.md), in-sheet sub-sections, bounded cards, [SideSheet](../side-sheet/side-sheet.md) drawer columns, and any host that needs a leading title + one trailing commit.
+
+**Reach for this when** a labelled block needs an `onSurface` heading and at most one trailing commit (See-all link, drill-in chevron, or sort dropdown). **Skip when** the block needs only a quiet muted group label — that is the family's [Sub](./sub.md) (`<SubHeader>`); when the block has multiple actions; the trailing affordance is a destructive commit; or the surrounding host already owns a heading at the same rung.
+
+**Layout inset.** `full-bleed` — transparent background, owns its inline padding internally (the same model as the family's [Sub](./sub.md) member). The inline inset is `container.md` (16) — the same content rail the List rows / Feed items it heads pay — so a bare `<Header>` and the content beneath it land on one shared rail with no host help; asymmetric block padding `stack.lg` (24) above / `stack.md` (16) below carries the heading's own vertical rhythm. Drop it directly above the labelled region as a sibling, never inside a `padding-inline` wrapper, and don't pay the rail again on the host. A bundling host (Carousel, DirectoryList, NavList, SideSheet column) stays full-bleed — it adds no inline padding of its own — and absorbs only Header's block padding into its stack rhythm: Header's 24-above replaces the host's leading inset, its 16-below is the header↔body gap (one gutter, paid once).
+
+## Default
+
+Section-style heading with a trailing Text Button "See all" link. Two sizes diverge on label typography: `large` = `sys.typo.heading.md` (20 / Semibold), `medium` = `sys.typo.heading.sm` (16 / Semibold).
+
+```preview
+header/main/default
+---
+import { Header } from '@teamblind-chorus/ui';
+
+<Header
+  label="Recommended channels"
+  headerAction={{ label: 'See all', href: '#all' }}
+/>
+```
+
+## Use cases
+
+### With drill-in chevron
+
+`trailingIcon` mode — the chevron is a [Button `variant="icon"`](../button/icon.md) at `size="medium"` (32 × 32 capsule, 16-glyph) that owns its own tap target. The chevron paints in `onSurfaceVariant` and rotates -90° to read as chevron-right. The surrounding `<header>` element stays non-interactive — clicks land on the Icon Button, not on the row chrome. Use when the trailing affordance is "open this surface", not "commit a labelled action". `headerAction` and `trailingIcon` are mutually exclusive.
+
+```preview
+header/main/with-icon-action
+---
+import { Header } from '@teamblind-chorus/ui';
+
+<Header
+  size="medium"
+  label="My channels"
+  trailingIcon
+  onClick={() => {}}
+/>
+```
+
+### With dropdown
+
+`headerDropdown` mode — the trailing affordance is a [Text Button dropdown](../button/text.md#dropdown) (`size="xsmall"`, default appearance) whose **label is the current value** ("Top", "Newest", "All time") and whose trailing chevron flips with `open` as a state signal. Use when the heading row needs an inline sort / filter / range disclosure — "Recommended channels [Top ▾]", "Posts [Last 7 days ▾]". Consumer owns the menu surface (Menu, popover, ListBox) and the `open` state; Header only renders the trigger.
+
+`headerAction`, `trailingIcon`, and `headerDropdown` are mutually exclusive — priority is `trailingIcon` > `headerAction` > `headerDropdown` when more than one is set.
+
+```preview
+header/main/with-dropdown
+---
+import { useState } from 'react';
+import { Header } from '@teamblind-chorus/ui';
+
+function Example() {
+  const [open, setOpen] = useState(false);
+  return (
+    <Header
+      label="Recommended channels"
+      headerDropdown={{
+        label: 'Top',
+        open,
+        onClick: () => setOpen((v) => !v),
+      }}
+    />
+  );
+}
+```
+
+### Label only
+
+Set only `label` (omit `headerAction`, `trailingIcon`, and `headerDropdown`) for a labelled region that needs a heading without a trailing affordance. The row collapses to a single heading at the requested size — no spacer, no empty container.
+
+```preview
+header/main/label-only
+---
+import { Header } from '@teamblind-chorus/ui';
+
+<Header label="Recommended channels" />
+```
+
+## Slots
+
+- **container** — outer row. Flex with `space-between`; label leads, action / icon / dropdown trails, 8px (`layout.inline.md`) gap. Full-bleed — transparent background and its own padding: `container.md` (16) inline (the shared content rail), `stack.lg` (24) block-start, `stack.md` (16) block-end — so the label lands on the same rail as the rows beneath it; bundling hosts add no inline padding of their own and absorb only the block padding. Stays a non-interactive `<header>` / `<div>` — the trailing affordance owns its own hit target.
+- **label** *(optional)* — heading text. `<h3>` by default; override the wrapper with `as="div"` when the surrounding host already owns the heading semantics. Color `sys.color.onSurface`. Typo per size.
+- **action** *(optional, headerAction mode)* — trailing Text Button. Fixed at `size="xsmall"`, `appearance="accent"`.
+- **icon** *(optional, trailingIcon mode)* — trailing [Icon Button](../button/icon.md) (`variant="icon"` `size="medium"`) hosting a 16px glyph (canonical: chevron-right). Its own tap target — clicks land on the Icon Button, not the surrounding header. Supply `aria-label` for the icon-only button (defaults to `"Open <label>"` when `label` is a string).
+- **dropdown** *(optional, headerDropdown mode)* — trailing [Text Button dropdown](../button/text.md#dropdown) (`size="xsmall"`, default appearance). Label is the current value; trailing chevron flips between `ChevronDownIcon` (closed) and `ChevronUpIcon` (open) tied to `headerDropdown.open`. Owns its own tap target — clicks land on the dropdown trigger, not the surrounding header.
+
+## Behavior
+
+- **Empty render** — when `label`, `headerAction`, `trailingIcon`, and `headerDropdown` are all omitted, Header renders nothing.
+- **Alignment** — label and trailing affordance share the row's centre line. The label never wraps; the trailing keeps intrinsic width and never grows.
+- **Mode exclusivity** — `headerAction`, `trailingIcon`, and `headerDropdown` are mutually exclusive. Priority when more than one is set: `trailingIcon` > `headerAction` > `headerDropdown`.
+
+## Composition
+
+- Inside [Carousel](../carousel/carousel.md) — rendered automatically as `size="large"` + `headerAction` mode.
+- Standalone — drop above any labelled region (`List`, `Feed`, `PostCarousel`, `Banner`, a bounded card body).
+- Inside a [SideSheet](../side-sheet/side-sheet.md) drawer column — `size="medium"` is the canonical rung; pair with `List` compact below.
+- Inside a [BottomSheet](../bottom-sheet/bottom-sheet.md) content slot — `size="medium"` so the heading does not compete with the sheet's own 20-rung title.

package/agents/components/header/main.spec.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Header",
+  "family": "header",
+  "subcomponent": "main",
+  "description": "The loud member of the Header family — a labelled `onSurface` heading + optional trailing 'See all' Text Button. The leading label is rendered as a semantic `<h3>` by default; consumers may override the wrapping element via the `as` prop (e.g. `as=\"div\"` when the host already owns the heading semantics). Two sizes diverge only on the label typography — anatomy (slot grammar, trailing-button binding, alignment) is identical. Reached as `<Header>` (the family's primary export); its quieter sibling is [Sub](./sub.md) (`<SubHeader>`), a muted 14 group label. Full-bleed (mirrors Sub): a transparent background and its own inline padding — `container.md` (16), the same rail the List rows / Feed items it heads pay — so a bare `<Header>` and the content beneath it land on one shared rail with no host help. Asymmetric block padding (`stack.lg` 24 above, `stack.md` 16 below) carries the heading's own vertical rhythm. Hosts that bundle Header above their content (Carousel, DirectoryList, NavList, SideSheet column) stay full-bleed (they add no inline padding of their own) and absorb only the block padding into their stack rhythm — the 'one gutter, paid once' rule.",
+  "element": "header",
+  "props": {
+    "size": {
+      "type": "literal",
+      "values": ["large", "medium"],
+      "default": "large",
+      "description": "Label typography rung. `large` (default) — `sys.typo.heading.md` (20 / Semibold) — the canonical section heading used by Section and other top-level page regions. `medium` — `sys.typo.heading.sm` (16 / Semibold) — denser host surfaces (in-sheet sub-section, bounded card, drawer column heading, secondary regions inside an already-headed page)."
+    },
+    "label": {
+      "type": "string",
+      "optional": true,
+      "description": "Leading heading text. Single line; the consumer truncates upstream if the host width is too narrow."
+    },
+    "headerAction": {
+      "type": "object",
+      "optional": true,
+      "description": "Trailing Text Button binding. Object: `{ label, href, onClick }`. Rendered as a Text Button at `size=\"xsmall\"`, `appearance=\"accent\"`. The link-affordance rule keeps the navigational intent in the accent tone across hosts. Mutually exclusive with `trailingIcon`."
+    },
+    "trailingIcon": {
+      "type": "node",
+      "optional": true,
+      "description": "Drill-in [Icon Button](../button/icon.md) mode. Pass `true` to render the canonical chevron-right glyph inside a Button `variant=\"icon\"` `size=\"medium\"` (32 × 32 capsule, 16-glyph), or pass any 16px icon node to override the glyph. The trailing Icon Button owns its own tap target via `onClick` / `href`; the surrounding `<header>` element stays non-interactive. Supply an `aria-label` for the icon-only button (defaults to `\"Open <label>\"` when `label` is a string). Mutually exclusive with `headerAction` and `headerDropdown`."
+    },
+    "headerDropdown": {
+      "type": "object",
+      "optional": true,
+      "description": "Trailing [Text Button dropdown](../button/text.md#dropdown) binding. Object: `{ label, onClick, open, 'aria-haspopup'?, 'aria-controls'? }`. Rendered as a Text Button at `size=\"xsmall\"` with the default appearance — label IS the current selected value ('Top', 'Last 7 days', 'All time'), and the trailing chevron flips between `ChevronDownIcon` (when `open` is falsy) and `ChevronUpIcon` (when `open` is true) as a state signal. Consumer owns the menu surface and the `open` state. Mutually exclusive with `headerAction` and `trailingIcon` — priority `trailingIcon` > `headerAction` > `headerDropdown` when more than one is set."
+    },
+    "onClick": {
+      "type": "function",
+      "optional": true,
+      "description": "Click handler. Honored when `trailingIcon` is set — wired to the trailing Icon Button's `onClick`."
+    },
+    "href": {
+      "type": "string",
+      "optional": true,
+      "description": "Link href. Honored when `trailingIcon` is set — wired to the trailing Icon Button."
+    },
+    "as": {
+      "type": "literal",
+      "values": ["header", "div"],
+      "default": "header",
+      "description": "Wrapping element. Defaults to `<header>` for top-level / labelled-region hosts; use `as=\"div\"` when the surrounding host already carries the section semantics. The wrapper itself is never interactive — in `trailingIcon` mode the click target sits on the trailing Icon Button, not the wrapper."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Outer row. Flex with `space-between` so the label and the trailing action sit on opposite edges, separated by an 8px (`layout.inline.md`) gap. Full-bleed — transparent background and its own padding: `container.md` (16) inline (the shared content rail), `stack.lg` (24) block-start, `stack.md` (16) block-end — so the label lands on the same rail as the rows beneath it with no host help; bundling hosts add no inline padding of their own and absorb only the block padding."
+    },
+    "label": {
+      "required": false,
+      "description": "Heading text. `<h3>` by default. Size `large` → `sys.typo.heading.md`; size `medium` → `sys.typo.heading.sm`. Color `sys.color.onSurface`."
+    },
+    "action": {
+      "required": false,
+      "description": "Trailing Text Button. Fixed at `size=\"xsmall\"`, `appearance=\"accent\"`. The label string comes from `headerAction.label`. Mutually exclusive with the icon slot below."
+    },
+    "icon": {
+      "required": false,
+      "description": "Trailing [Icon Button](../button/icon.md) (Button `variant=\"icon\"` `size=\"medium\"`) hosting a 16px glyph (canonical: chevron-right). Its own tap target — clicks land on the Icon Button, not the surrounding header. Mutually exclusive with the action and dropdown slots.",
+      "accepts": ["button"],
+      "rendersAs": "button:icon"
+    },
+    "dropdown": {
+      "required": false,
+      "description": "Trailing [Text Button dropdown](../button/text.md#dropdown) (`size=\"xsmall\"`, default appearance) when `headerDropdown` is set. Label is `headerDropdown.label`; trailing chevron flips between `ChevronDownIcon` (closed) and `ChevronUpIcon` (open) tied to `headerDropdown.open`. Owns its own tap target — clicks land on the dropdown trigger, not the surrounding header. Mutually exclusive with the action and icon slots.",
+      "accepts": ["button"],
+      "rendersAs": "button:text (dropdown)"
+    }
+  },
+  "sizing": {
+    "containerGap": "sys.layout.inline.md",
+    "containerAlign": "center",
+    "containerJustify": "space-between",
+    "large": {
+      "labelTypo": "sys.typo.heading.md (20 / Semibold)"
+    },
+    "medium": {
+      "labelTypo": "sys.typo.heading.sm (16 / Semibold)"
+    },
+    "labelColor": "sys.color.onSurface",
+    "actionSize": "Text Button xsmall, appearance accent",
+    "iconButtonSize": "Button variant=\"icon\" size=\"medium\" (32 × 32 capsule, 16-glyph)",
+    "iconColor": "sys.color.onSurfaceVariant (glyph inherits via `currentColor` from the Icon Button)"
+  },
+  "appearance": {
+    "background": "transparent",
+    "paddingInline": "sys.layout.container.md",
+    "paddingBlockStart": "sys.layout.stack.lg",
+    "paddingBlockEnd": "sys.layout.stack.md",
+    "note": "Full-bleed: transparent background (Header paints on whatever surface tier hosts it) + its own block & inline padding. Inline `container.md` (16) IS the shared content rail — the same inset the List rows / Feed items beneath the Header pay — so a bare `<Header>` and its content align with no host help. Block is asymmetric — `stack.lg` (24) above to break from the previous region, `stack.md` (16) below to bind the heading to the block it labels. Bundling hosts (Carousel, DirectoryList, NavList, SideSheet column) stay full-bleed — they add no inline padding of their own — and absorb only the block padding into their stack rhythm (Header's 24-above replaces the host's leading inset, its 16-below is the header↔body gap) — the 'one gutter, paid once' rule. NEVER give Header an opaque fill or wrap it in a `padding-inline` div."
+  },
+  "states": {
+    "description": "Header itself has no lifecycle states. The trailing action carries Text Button's hover / pressed / focus."
+  },
+  "behavior": {
+    "rendering": "When `label`, `headerAction`, `trailingIcon`, and `headerDropdown` are all omitted, the component renders nothing (no empty container). When only `label` is set the row collapses to a heading-only Header — the canonical 'labelled region without affordance' case.",
+    "alignment": "Label and trailing affordance share the row's centre line; the label never wraps, the affordance keeps intrinsic width and never grows.",
+    "linkAffordance": "In `headerAction` mode, the trailing action is always a Text Button — never a Standard Button, never a raw `<a>`, never an icon. In `trailingIcon` mode, the chevron is rendered as a Button `variant=\"icon\"` `size=\"medium\"` that owns its own tap target — the surrounding `<header>` element is decorative and never interactive. In `headerDropdown` mode, the trigger is rendered as a Text Button `size=\"xsmall\"` with a state-signalling chevron, and the consumer owns the menu surface and the `open` state.",
+    "modeExclusivity": "`headerAction`, `trailingIcon`, and `headerDropdown` are mutually exclusive — priority when more than one is set: `trailingIcon` > `headerAction` > `headerDropdown`. Pick one mode per host."
+  },
+  "forbidden": [
+    "non-Text-Button trailing action in `headerAction` mode (Standard Button, Icon Button, raw <a>)",
+    "label larger than heading-md or smaller than heading-sm — pick the size dial, do not custom-tune the typo",
+    "headerAction without an href or onClick — the link affordance must commit somewhere",
+    "trailingIcon without an onClick or href — an icon-only header that is non-interactive is decorative noise; reach for a labelled Section header instead",
+    "headerDropdown without `label` (the trigger's label IS the current value — empty label is meaningless) or without `onClick` (the trigger must commit somewhere)",
+    "multiple trailing modes together (headerAction + trailingIcon, headerAction + headerDropdown, trailingIcon + headerDropdown) — pick one"
+  ]
+}

package/agents/components/header/sub.md

@@ -0,0 +1,129 @@
+# Sub
+
+Quiet section-dividing label — a 14px (`sys.typo.label.md`, 14 / Semibold) line in the muted `sys.color.onSurfaceVariant` tone that names the group of rows beneath it ("Following", "More Topics to follow"). The muted tone is the dividing device: it reads as a region label rather than a heading that competes with the page title, while the label-weight typo keeps it from dissolving into body copy. Rendered as a semantic `<h3>` by default so screen-reader heading navigation lands on the group label.
+
+It may carry one quiet trailing affordance — a single [Text Button](../button/text.md) `action` ("See all", "Edit", "Manage") — for a region-level commit that stays subordinate to the muted label. Icon drill-in and dropdown disclosure are *not* SubHeader's: those belong on [Main](./main.md), whose louder `onSurface` heading earns the heavier affordance set.
+
+**Reach for this when** a stack of rows splits into named groups and the boundary needs a quiet word, not a loud heading — a followed set above a suggested set, settings rows clustered by theme — optionally with a single quiet "See all" / "Edit" commit on the trailing edge. **Skip when** the region needs a louder section *heading* (`onSurface`, 16 / 20) or a drill-in chevron / sort dropdown — that is [Main](./main.md); when the break between two regions is purely visual with no label — that is [Divider](../divider/divider.md); or when the group label belongs *inside* a bounded surface that already carries its own heading rung. The split from Main is the tone/weight axis (muted label vs heading), not whether a trailing commit exists.
+
+**Layout inset.** `full-bleed` — SubHeader pays its own `16px` (`sys.layout.container.md`) inline inset so the label aligns with the full-bleed [List](../list/list.md) rows it heads, plus `24px` block padding above (to break from the previous region) and `8px` below (to bind the label to its group). Drop it as a direct child of the page shell directly above the group it labels; do **not** wrap it in another `padding-inline` / `px-*` / `style={{ padding }}` div, or the label lands at a different inset than the rows beneath it. Inside a bounded surface (Card / Dialog / BottomSheet / SideSheet), apply the negative-margin opt-out — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+A single muted group label. Pair it directly above the rows it names.
+
+```preview
+header/sub/default
+---
+import { SubHeader } from '@teamblind-chorus/ui';
+
+<SubHeader label="Following" />
+```
+
+## Use cases
+
+### Grouping a list
+
+The canonical placement — a SubHeader labels each group of rows, splitting one stacked list into named sections. The muted label sits at the same `16px` inset as the rows; the block rhythm (more above, less below) reads as "new group starts here".
+
+```preview
+header/sub/grouping-a-list
+---
+import { useState } from 'react';
+import { SubHeader, List } from '@teamblind-chorus/ui';
+
+function Example() {
+  const [value, setValue] = useState('product');
+  return (
+    <div style={{ background: 'var(--sys-color-surface)', display: 'flex', flexDirection: 'column' }}>
+      <SubHeader label="Following" />
+      <List
+        variant="radio"
+        value={value}
+        onChange={setValue}
+        aria-label="Following"
+        items={[
+          { value: 'tech',    label: 'Tech Industry' },
+          { value: 'swe',     label: 'Software Engineering Career' },
+          { value: 'product', label: 'Product Management' },
+          { value: 'design',  label: 'Design Career' },
+        ]}
+      />
+      <SubHeader label="More Topics to follow" />
+      <List
+        variant="radio"
+        value={value}
+        onChange={setValue}
+        aria-label="More topics to follow"
+        items={[
+          { value: 'misc',     label: 'Misc.' },
+          { value: 'visa',     label: 'Work Visa' },
+          { value: 'jobs',     label: 'Job Opening' },
+          { value: 'startups', label: 'Startups' },
+        ]}
+      />
+    </div>
+  );
+}
+```
+
+### With a trailing action
+
+Pass `action={{ label, href, onClick }}` for a single quiet commit on the trailing edge — "See all" above a previewed group, "Edit" above an editable cluster. The wrapper becomes a full-bleed flex row: the muted label holds the leading edge, the [Text Button](../button/text.md) (`size="xsmall"`, `appearance="accent"`) hugs the trailing edge at the same 16 inset. The action stays subordinate to the label — this is still a quiet region marker, not a [Main](./main.md) heading row. Use Main instead when the region needs the louder `onSurface` heading, an icon drill-in, or a sort dropdown.
+
+```preview
+header/sub/with-action
+---
+import { SubHeader, List } from '@teamblind-chorus/ui';
+
+<div style={{ background: 'var(--sys-color-surface)', display: 'flex', flexDirection: 'column' }}>
+  <SubHeader label="Following" action={{ label: 'See all', href: '#all' }} />
+  <List
+    aria-label="Following"
+    items={[
+      { label: 'Tech Industry' },
+      { label: 'Software Engineering Career' },
+      { label: 'Product Management' },
+    ]}
+  />
+</div>
+```
+
+### Host owns the heading
+
+When the surrounding host already carries the section semantics, override the wrapping element with `as="div"` so the document outline doesn't gain a stray heading — the label keeps its muted tone and inset.
+
+```preview
+header/sub/as-div
+---
+import { SubHeader } from '@teamblind-chorus/ui';
+
+<SubHeader as="div" label="More Topics to follow" />
+```
+
+## Slots
+
+- **container** — the full-bleed label line. `16px` (`layout.container.md`) inline inset to align with the rows beneath, `24px` (`layout.stack.lg`) block padding above and `8px` (`layout.stack.xs`) below. Non-interactive. Without `action` the container *is* the heading element (`as`); with `action` it is a non-semantic flex `<div>` (`space-between`, `8px` `layout.inline.md` gap) holding the nested label and the trailing action on opposite edges.
+- **label** — required. Section label text. `<h3>` by default (override via `as`). Typo `sys.typo.label.md` (14 / Semibold); color `sys.color.onSurfaceVariant`. Single line.
+- **action** — optional. Trailing [Text Button](../button/text.md) (`size="xsmall"`, `appearance="accent"`) from `action={{ label, href, onClick }}`. The one trailing affordance SubHeader carries; owns its own tap target. Present only when `action` is set.
+
+## Anatomy
+
+| Slot      | Token bindings |
+|-----------|----------------|
+| container | `sys.layout.container.md` (16) inline padding, `sys.layout.stack.lg` (24) block-start, `sys.layout.stack.xs` (8) block-end, full inline width, no border, no radius; in `action` mode flex `space-between` with `sys.layout.inline.md` (8) gap |
+| label     | `sys.typo.label.md` (14 / Semibold) typo, `sys.color.onSurfaceVariant` color |
+| action    | [Text Button](../button/text.md) `size="xsmall"`, `appearance="accent"`; intrinsic width, never grows |
+
+## Appearance
+
+Single appearance — SubHeader has no size axis and no emphasis axis. The muted `onSurfaceVariant` tone at the 14 / Semibold `label.md` rung is the dividing device; a tone down from Header's `onSurface` heading so the label reads as a region marker, not a competing title. When an `action` is present the trailing Text Button supplies the one pop of accent; the label tone is unchanged.
+
+**Transparent background.** The container paints no fill — it is `transparent` — so the label composes directly on whatever surface tier hosts it (`surface`, `surfaceContainer`, a tonal band, a Sheet body) and stays harmonious on any background. The dividing device is the muted tone, never a painted fill; do not give SubHeader an opaque background.
+
+## Behavior
+
+- **Empty render.** When neither `label` nor `children` is set, SubHeader renders nothing — no empty container, even if `action` is set (a trailing button with no label is meaningless).
+- **Single action only.** SubHeader carries at most one trailing affordance, and only a Text Button (`action`). It supports no icon drill-in and no sort dropdown — those stay [Main](./main.md)'s, where the louder `onSurface` heading earns the heavier affordance set. The split from Main is the tone/weight axis (muted label at 14 vs heading at 16 / 20), not whether a trailing commit exists.
+- **Action semantics.** In `action` mode the wrapper is a non-semantic flex `<div>` and the label keeps its heading element (`as`) nested on the leading edge, so the trailing button never folds into the heading's accessible name. The button owns its own tap target; the row chrome stays non-interactive.
+- **Heading by default.** The label renders as `<h3>` so screen-reader heading navigation lands on the group label. Override `as` to fit the host's outline, or `as="div"` when the host already owns the section semantics.

package/agents/components/header/sub.spec.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "SubHeader",
+  "family": "header",
+  "subcomponent": "sub",
+  "description": "The quiet member of the Header family — a section-dividing label. A single line of 14px (`sys.typo.label.md`, 14 / Semibold) text in the muted `sys.color.onSurfaceVariant` tone that names the group of rows beneath it (\"Following\", \"More Topics to follow\"). No size axis — the muted tone is the dividing device, and the label-weight typo keeps it reading as a section label rather than body copy. Reached as `<SubHeader>`; its louder sibling is [Main](./main.md) (`<Header>`), an `onSurface` heading at 16 / 20. Optionally carries a single trailing `action` Text Button (`size=\"xsmall\"`, `appearance=\"accent\"`) for a quiet region-level commit (\"See all\", \"Edit\", \"Manage\"); icon drill-in and dropdown disclosure stay Main's territory, where the louder `onSurface` heading tone belongs. Rendered as a semantic `<h3>` by default so screen-reader heading navigation lands on the group label; consumers may override the wrapping element via the `as` prop (e.g. `as=\"div\"` when the host already owns the heading semantics). Full-bleed: pays the same 16 (`sys.layout.container.md`) inline inset as the List rows it labels, with asymmetric block padding (24 above to break from the previous region, 8 below to bind the label to its group).",
+  "element": "h3",
+  "props": {
+    "label": {
+      "type": "string",
+      "optional": true,
+      "description": "The section label text (\"Following\", \"More Topics to follow\"). Single line; the consumer keeps it short. `children` may be passed instead and takes precedence — `label` is the canonical string form."
+    },
+    "action": {
+      "type": "object",
+      "optional": true,
+      "description": "Trailing Text Button binding. Object: `{ label, href, onClick }`. Rendered as a Text Button at `size=\"xsmall\"`, `appearance=\"accent\"` — the one trailing affordance SubHeader carries, for a quiet region-level commit (\"See all\", \"Edit\", \"Manage\"). When set, the wrapper becomes a full-bleed flex row and the label is nested as the heading (`as`) on the leading edge so the heading's accessible name never absorbs the button. Mirrors Header's `headerAction` binding; SubHeader supports no icon or dropdown mode (those stay Header's, where the louder heading tone belongs)."
+    },
+    "as": {
+      "type": "literal",
+      "values": ["h2", "h3", "h4", "div"],
+      "default": "h3",
+      "description": "Wrapping element for the label. Defaults to `<h3>` so the muted label still registers as a heading for the group beneath it; use a different heading level to fit the host's document outline, or `as=\"div\"` when the surrounding host already carries the section semantics. The label element is never interactive — in `action` mode the click target sits on the trailing Text Button, and the flex-row wrapper that holds both is a non-semantic `<div>`."
+    },
+    "children": {
+      "type": "node",
+      "optional": true,
+      "description": "Label content — overrides `label` when both are set. Use the `label` string for the canonical case; `children` is the escape hatch for inline composition."
+    },
+    "className": {
+      "type": "string",
+      "optional": true,
+      "description": "Composes with the component's own class. Use sparingly — SubHeader exposes its tone and inset through the spec; overriding them breaks the alignment-with-rows and muted-divider contracts."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "The full-bleed label line. Pays `sys.layout.container.md` (16) inline inset to align with the List rows beneath, `sys.layout.stack.lg` (24) block padding above and `sys.layout.stack.xs` (8) below. Non-interactive. Without `action` the container IS the heading element (`as`); with `action` it is a non-semantic flex `<div>` (`space-between`, `sys.layout.inline.md` gap) holding the nested label and the trailing action on opposite edges."
+    },
+    "label": {
+      "required": false,
+      "description": "Section label text. `<h3>` by default (overridable via `as`). Typo `sys.typo.label.md` (14 / Semibold); color `sys.color.onSurfaceVariant`. Single line.",
+      "accepts": ["text"]
+    },
+    "action": {
+      "required": false,
+      "description": "Optional trailing Text Button. Fixed at `size=\"xsmall\"`, `appearance=\"accent\"`; label comes from `action.label`. Owns its own tap target — clicks land on the button, not the surrounding row. Present only when `action` is set.",
+      "accepts": ["button"],
+      "rendersAs": "button:text"
+    }
+  },
+  "appearance": {
+    "containerFill": "transparent",
+    "labelTypo": "sys.typo.label.md",
+    "labelColor": "sys.color.onSurfaceVariant",
+    "paddingInline": "sys.layout.container.md",
+    "paddingBlockStart": "sys.layout.stack.lg",
+    "paddingBlockEnd": "sys.layout.stack.xs",
+    "note": "The container paints NO fill — `transparent` — so the muted label composes directly on whatever surface tier it sits on (surface, surfaceContainer, a tonal band, a Sheet body) and stays harmonious on any host. The dividing device is the tone, not a painted background. The muted `onSurfaceVariant` tone is a tone down from Header's `onSurface` heading so the label reads as a region marker, not a competing title. The 14 / Semibold `label.md` rung is the section-label weight: smaller than any Header heading (16 / 20) but emphatic enough to read as a label over the rows beneath it. Asymmetric block padding (24 above / 8 below) breaks the label from the previous region and binds it to the group below."
+  },
+  "behavior": {
+    "rendering": "When neither `label` nor `children` is set, SubHeader renders nothing (no empty container) — even when `action` is set, since a trailing button with no label is meaningless.",
+    "singleAction": "SubHeader carries at most one trailing affordance, and only a Text Button (`action`). It supports no icon drill-in and no dropdown disclosure — those stay Header's, where the louder `onSurface` heading tone reads as a heading-with-affordance rather than a quiet labelled region. The distinction from Header is the tone/weight axis (muted `onSurfaceVariant` label at 14 vs `onSurface` heading at 16/20), not the presence of a trailing commit.",
+    "actionSemantics": "In `action` mode the wrapper is a non-semantic flex `<div>` and the label keeps its heading element (`as`) nested on the leading edge, so the trailing Text Button never folds into the heading's accessible name. The button owns its own tap target; the row chrome is non-interactive.",
+    "fullBleed": "Pays its own 16 (`container.md`) inline inset so the label aligns with the full-bleed List rows it heads. Must not be wrapped in a padding-inline container, or the label drifts off the row inset."
+  },
+  "states": {
+    "description": "SubHeader itself has no lifecycle states — the label is a static, non-interactive marker. When `action` is set, the trailing Text Button carries its own hover / pressed / focus."
+  },
+  "forbidden": [
+    "SubHeader painted in `onSurface` or any non-muted tone — the muted `onSurfaceVariant` IS the dividing device; a full-strength tone makes it compete with the page heading (reach for Header instead)",
+    "SubHeader given an opaque container fill (`surface`, `surfaceContainer`, any background) — the container is `transparent` so the label harmonizes on any host surface tier; a painted fill clashes the moment it sits on a non-surface band",
+    "SubHeader given a trailing icon drill-in or dropdown disclosure — only a single Text Button `action` is allowed; an icon/dropdown affordance belongs on Header",
+    "SubHeader given more than one trailing action — the row carries a single quiet commit, not a button cluster",
+    "SubHeader `action` rendered as anything but a Text Button (Standard Button, Icon Button, raw <a>) — the link affordance keeps the navigational intent in the accent tone, mirroring Header",
+    "SubHeader typo dialled above `label.md` (14 / Semibold) — a larger or louder rung is a Header heading, not a quiet group label",
+    "SubHeader wrapped in a padding-inline div or `style={{ paddingInline }}` — it is full-bleed and pays its own 16 inset to align with the rows beneath",
+    "SubHeader rendered as a raw <p> / <span> with Tailwind — the label owns its tone, inset, and block rhythm through the spec"
+  ]
+}

package/agents/components/list/accordion.md

@@ -0,0 +1,183 @@
+# Accordion
+
+Expandable-row List sub. Each item exposes a List-row trigger (label + auto-rendered trailing chevron that rotates `180°` on expand) and a body that paints below it when open. Rows tile flush with the family hairline `outlineVariant` divider between them; an extra rule paints between the open trigger and its child row group.
+
+**Reach for this when** a list of titled sections is too long to keep open at once — FAQs, T&C sections, expandable filter groups, settings groups with infrequent edits, hierarchical menus (companies → channels, regions → cities). **Skip when** bodies are short enough to read inline (use [Carousel](../carousel/carousel.md) per group), the user needs to act on labels (use a [List/standard](./standard.md) drill-in row or [List/radio](./radio.md)), or every item should be visible at once (stack [Carousel](../carousel/carousel.md)s).
+
+Row geometry, label typography, divider, state overlays, and inward focus ring all delegate to the [family-wide rules](./list.md); this sub documents only the expand/collapse contract and the top group-divider between trigger and child rows.
+
+**Layout inset.** `full-bleed` — direct child of the page shell, edge-to-edge. Each row pays its own `16px inline / 8px block` padding via `layout.container.*`. Do **not** wrap in another `padding-inline` / `px-*` / `style={{ padding: … }}` div — the page rail will double-pay. Inside a bounded surface, apply the negative-margin opt-out — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+Single-mode form. One item open at a time; clicking an open item collapses it (`collapsible={true}` by default).
+
+```preview
+accordion/default
+---
+import { Accordion } from '@teamblind-chorus/ui';
+
+<Accordion type="single" defaultValue="why" aria-label="Frequently asked questions">
+  <Accordion.Item value="why" label="Why does Blind anonymise posts?">
+    Anonymity is the only way employees can compare salaries, escalate misconduct, or ask candid culture questions without retaliation. Verified company badges keep the channel trustworthy without unmasking the author.
+  </Accordion.Item>
+  <Accordion.Item value="verify" label="How is my company verified?">
+    Sign up with your corporate email — the verification code lands in your inbox, never on a public profile. Once verified, the badge persists across job changes (we re-verify when you update your employer).
+  </Accordion.Item>
+  <Accordion.Item value="data" label="What can other users see?">
+    Other users see your company badge, your career stage, and the content you post. Your email, name, and exact title are never exposed.
+  </Accordion.Item>
+</Accordion>
+```
+
+## Use cases
+
+### Multiple
+
+`type="multiple"` lets the user open any number of items at once. Use when rows are independent and the user reads across several — comparing T&C clauses, expanding filter groups, reviewing policy sections.
+
+```preview
+accordion/multiple
+---
+import { Accordion } from '@teamblind-chorus/ui';
+
+<Accordion type="multiple" defaultValue={['salary', 'tenure']} aria-label="Active filters">
+  <Accordion.Item value="salary" label="Compensation">
+    Filter posts by salary range, equity, sign-on bonus.
+  </Accordion.Item>
+  <Accordion.Item value="tenure" label="Tenure">
+    Filter authors by years at current company.
+  </Accordion.Item>
+  <Accordion.Item value="role" label="Role">
+    Filter by IC level, manager track, or specialty.
+  </Accordion.Item>
+</Accordion>
+```
+
+### Nested list
+
+When the body holds a same-kind row group rather than prose — directory sub-entries, settings sub-options, filter children, menu sub-items — drop a `<List>` into the content slot with `embedded={true}` so the list defers its own chrome to the host. The body recognises the embedded child via `:has([data-embedded='true'])` and switches to compact-host geometry: body inline padding flips from prose's `32 leading / 16 trailing` to `16 / 0` (sub-list stretches flush right), a hairline `outlineVariant` top group-divider paints via the body's `::before`, and sub-list rows compress to `body.sm` at `40px` min-height with inter-row dividers suppressed. Call sites pass no extra mode prop — dropping `<List embedded>` (or a nested `<Accordion embedded>`) activates it automatically.
+
+```preview
+accordion/nested-list
+---
+import { Accordion, List } from '@teamblind-chorus/ui';
+
+<Accordion type="single" defaultValue="invest-cast" aria-label="Company directory">
+  <Accordion.Item value="invest-fund" label="Invest Fund">
+    <List
+      variant="standard"
+      embedded
+      aria-label="Invest Fund roles"
+      items={[
+        { value: 'invest-fund-analyst',    label: 'Invest Fund + Analyst' },
+        { value: 'invest-fund-associate',  label: 'Invest Fund + Associate' },
+        { value: 'invest-fund-partner',    label: 'Invest Fund + Partner' },
+      ]}
+    />
+  </Accordion.Item>
+  <Accordion.Item value="invest-cast" label="Invest Cast">
+    <List
+      variant="standard"
+      embedded
+      aria-label="Invest Cast roles"
+      items={[
+        { value: 'invest-cast-acctg',      label: 'Invest Cast + Acctg' },
+        { value: 'invest-cast-admin',      label: 'Invest Cast + Admin' },
+        { value: 'invest-cast-biz-dev',    label: 'Invest Cast + Biz Dev' },
+        { value: 'invest-cast-consultant', label: 'Invest Cast + Consultant' },
+        { value: 'invest-cast-creative',   label: 'Invest Cast + Creative' },
+      ]}
+    />
+  </Accordion.Item>
+  <Accordion.Item value="invest-financial" label="INVEST Financial Corporation">
+    <List
+      variant="standard"
+      embedded
+      aria-label="INVEST Financial Corporation roles"
+      items={[
+        { value: 'invest-fin-advisor',   label: 'INVEST Financial + Advisor' },
+        { value: 'invest-fin-compliance',label: 'INVEST Financial + Compliance' },
+        { value: 'invest-fin-ops',       label: 'INVEST Financial + Ops' },
+      ]}
+    />
+  </Accordion.Item>
+</Accordion>
+```
+
+### Disabled item
+
+A `disabled` row fades to `sys.state.disabled` opacity and ignores click / keyboard activation. Stays in the DOM so surrounding items keep their stable index.
+
+```preview
+accordion/disabled-item
+---
+import { Accordion } from '@teamblind-chorus/ui';
+
+<Accordion type="single" aria-label="Account settings">
+  <Accordion.Item value="profile" label="Profile">
+    Display name, avatar, bio.
+  </Accordion.Item>
+  <Accordion.Item value="billing" label="Billing" disabled>
+    Available for verified enterprise accounts only.
+  </Accordion.Item>
+  <Accordion.Item value="notifications" label="Notifications">
+    Email, push, and in-app notification preferences.
+  </Accordion.Item>
+</Accordion>
+```
+
+## Slots
+
+- **container** — outer stack. Transparent fill so the host surface tone reads through. `role="region"` carries the accordion's accessible name (`aria-label`).
+- **item** — single expandable row. Hairline `outlineVariant` divider inset 16px on both inline edges, painted as an `::after` overlay on every row except the last.
+- **trigger** — header button. Holds the label and the auto-rendered trailing chevron. Same geometry as a List row (48px min-height, 8 × 16 padding). `aria-expanded` reflects open-state, `aria-controls` references the content region.
+- **label** — trigger label. `16 / Regular / onSurface` — matches the List family `label` spec so the trigger reads as a List row that happens to expand. Wraps to a second line; no truncation.
+- **chevron** — auto-rendered 16px `ChevronDownIcon`. Rotates `0°` → `180°` over 120ms `ease-out` on expand. Decorative.
+- **content** — body region. Paints below the trigger when open; toggled via the `hidden` attribute when closed. `min-height: 40px` keeps short single-line bodies on a touch-target rhythm. Two padding modes by content kind: *prose body* (text, icon, button, form-field) uses `32 leading / 16 trailing` inline padding so prose reads as nested inside the trigger's label column, body text at `body.sm` (one rung below the trigger label), no top group-divider. *Embedded row group* (`<List embedded>` or nested `<Accordion embedded>`, detected via `:has([data-embedded='true'])`) uses `16 / 0` inline padding with a hairline `outlineVariant` top divider via `::before`; sub-list rows compress to `body.sm` at `40px` min-height with no inter-row dividers.
+
+## Anatomy
+
+| Slot          | Token bindings |
+|---------------|----------------|
+| container     | Transparent fill, no padding (full-bleed, edge-to-edge) |
+| item          | Hairline `outlineVariant` divider inset 16px on both inline edges, omitted on the last row — family-wide List divider |
+| trigger       | 48px min-height, 8px block / 16px inline padding, full-row click target |
+| label         | `16 / Regular`, `onSurface` — matches the List `label` spec |
+| chevron       | 16 × 16, `onSurfaceVariant`, rotates 0° → 180° over 120ms `ease-out` |
+| content (prose)          | 8px block padding, `32 leading / 16 trailing` inline padding, `min-height: 40px`, `sys.typo.body.sm` (14 / Regular) at `onSurfaceVariant` |
+| content (embedded group) | 8px block padding, `16 leading / 0 trailing` inline padding; sub-list rows render at `body.sm` (14 / Regular), `min-height: 40px`, with `::after` row dividers suppressed |
+| divider       | `sys.borderWidth.hairline` × `sys.color.outlineVariant`, inset 16px on both inline edges via `::after` overlay |
+| groupDivider  | `sys.borderWidth.hairline` × `sys.color.outlineVariant`, inset 16px on both inline edges via `::before` overlay on the content body, painted ONLY when the body hosts a `<List embedded>` child group |
+
+## Appearance
+
+A single appearance — Accordion paints no fill of its own and offers no emphasis axis. The host surface tone reads through every row. Wrap the Accordion in a [Carousel](../carousel/carousel.md) when it needs its own labelled region.
+
+## States
+
+| State      | Overlay                       | Additional |
+|------------|-------------------------------|------------|
+| `default`  | —                             | Trigger paints at rest. |
+| `hovered`  | label tone at `sys.state.hover`   | Overlay paints across the trigger row only (not the open content). |
+| `pressed`  | label tone at `sys.state.pressed` | Overlay deepens; no other shift. |
+| `disabled` | overlay suppressed            | Whole item at `sys.state.disabled` opacity; `pointer-events: none`. |
+
+## Focus indicator
+
+Inward 3-layer ring painted inside the trigger's footprint via a `::before` overlay. Trigger: `:focus-visible`. Items tile flush with only a hairline divider between them, so an outward ring would overlap the divider and the neighbouring row — see [Focus ring composition](../../DESIGN.md#focus-ring-composition).
+
+## Behavior
+
+- **Edge-to-edge composition.** `layoutInset: full-bleed` — direct child of the page shell. Wrapping in another `padding-inline` / `px-*` div double-pays the rail. Use the negative-margin opt-out inside a bounded surface.
+- **Inset divider.** 1px `outlineVariant` rule inset 16px on both inline edges — same as every other List sub.
+- **Indented prose.** Expanded body sits one extra 16px in from the trigger's label edge for parent ↔ child hierarchy.
+- **Embedded groups switch the body to compact-host geometry.** When the body hosts a `<List embedded>`, three things change at once: body inline padding flips from `32 / 16` to `16 / 0` (sub-list flush right); a hairline `outlineVariant` rule paints at the body's top edge so parent and child read as a hierarchy; sub-list rows compress to `body.sm` at `40px` min-height with no inter-row dividers.
+- **Whole trigger is the click target.** Chevron is decorative.
+- **Element swap.** Trigger is `<button>`; content region is `<div role="region">` with `hidden` toggled.
+- **Keyboard.** Space / Enter toggle. Arrow up/down moves focus between triggers.
+- **Single mode.** Opening one item closes the previously open one. With `collapsible={true}` (default), clicking the open item closes it.
+- **Multiple mode.** Each trigger toggles independently. `value` is a `string[]`.
+- **Wrap, not truncate.** Trigger labels wrap to a second line; the row grows.
+- **Content min-height.** Open content carries a `40px` floor so short bodies read as a distinct expanded row.
+- **Reduced motion.** Chevron rotation snaps instantly under `prefers-reduced-motion: reduce`.