@teamblind-chorus/ui 1.0.0

package/agents/components/badge/role.md

@@ -0,0 +1,100 @@
+# Role
+
+A tonal identity pill naming a user's role or title — anchored at the trailing edge of their metadata. Pale `primaryContainer` fill with a deep `onPrimaryContainer` label: informational, quiet, and clearly distinct from the [Update](./update.md) sub's brand-tone alert. Always rides beside a user identity — canonically the bare nickname at the end of the metadata row's second line, **exactly one badge per nickname** — never interactive. Two appearances: `default` (tonal primaryContainer) and `inverse` (near-black inverseSurface pair, reserved for the paid-expert **PRO** mark).
+
+**Reach for this when** the mark says *who the person is* — Channel owner (채널장), Verified (현직자), Moderator. **Skip when** the mark signals workflow state — pending / approved / rejected belong to [Status tag](../status-tag/status-tag.md) — or new-activity on a host — that's [Update](./update.md).
+
+**Layout inset.** inline — slot atom. The identity host places it (Metadata primary line, List row label); never a sibling of `full-bleed` page rows.
+
+## Default
+
+The role label in a content-growing pill: 16px (`ref.space.200`) min-height, 2 × 6 padding (`ref.space.25` × `ref.space.75`), 10px (`caption`) label, `radius.full` corner. Single rung — sized to ride inline beside caption-scale metadata text without stretching the row.
+
+```preview
+badge/role/default
+---
+import { Badge } from '@teamblind-chorus/ui';
+
+<Badge variant="role">Verified</Badge>
+```
+
+## Use cases
+
+### Inverse (PRO)
+
+`appearance="inverse"` swaps the fill to the high-contrast inverse pair (`sys.color.inverseSurface` / `sys.color.inverseOnSurface` — theme-aware, flips in dark mode). Reserved for **PRO**, the mark on paid professional users; never reach for it as a styling option on ordinary roles. Same geometry as default — only the fill pair changes.
+
+```preview
+badge/role/inverse
+---
+import { Badge } from '@teamblind-chorus/ui';
+
+<Badge variant="role" appearance="inverse">PRO</Badge>
+```
+
+### Canonical labels
+
+The product-canonical roles — **Channel owner** (채널장), **Verified** (현직자, the verified professional), and **PRO** (the paid professional, always on the inverse appearance). Labels display in English; any short role / title fits the same pill. Keep it to 1–2 words and one badge per person.
+
+```preview
+badge/role/labels
+---
+import { Badge } from '@teamblind-chorus/ui';
+
+<div style={{ display: 'flex', alignItems: 'center', gap: 'var(--sys-layout-inline-lg)' }}>
+  <Badge variant="role">Channel owner</Badge>
+  <Badge variant="role">Verified</Badge>
+  <Badge variant="role" appearance="inverse">PRO</Badge>
+</div>
+```
+
+### With metadata
+
+The canonical host — the trailing **nickname** item of [Metadata](../metadata/metadata.md)'s meta row (second line; the nickname displays bare, no @ prefix). Pass the pill through the meta item's `badge` field so it renders after the nickname link, *outside* the `<a>` (4px `inline.sm` gap — never link content). The badge annotates the person the way the timestamp annotates the post. **Exactly one badge rides the nickname** — when a user qualifies for several roles, pick the contextually dominant one; never stack.
+
+```preview
+badge/role/with-metadata
+---
+import { Badge, Metadata } from '@teamblind-chorus/ui';
+
+<Metadata
+  avatar={{ src: '…', alt: 'Jordan Lee' }}
+  name="Jordan Lee"
+  nameHref="#"
+  timestamp="2h"
+  meta={[
+    'Samsung Electronics',
+    'Semiconductor',
+    { label: 'siliconfox', href: '#', badge: <Badge variant="role">Verified</Badge> },
+  ]}
+/>
+```
+
+## Appearance
+
+Two appearances on a single emphasis axis — both theme-aware, no separate dark binding:
+
+| Appearance | Background | Label | Reserved for |
+|------------|------------|-------|--------------|
+| `default`  | `sys.color.primaryContainer` | `sys.color.onPrimaryContainer` | Ordinary role marks — Channel owner, Verified |
+| `inverse`  | `sys.color.inverseSurface`   | `sys.color.inverseOnSurface`   | The **PRO** paid-expert mark only |
+
+Never the brand pair — brand on a badge is the [Update](./update.md) activity marker, and a brand-filled role mark would read as an alert.
+
+## Slots
+
+- **label** — the role / title text. Required, single line, 1–2 words; the pill grows with content from the 16px square minimum.
+
+## Sizes
+
+Single rung.
+
+| Size   | Min-height / width     | Padding (block × inline)              | Label                                |
+|--------|------------------------|---------------------------------------|--------------------------------------|
+| medium | 16px (`ref.space.200`) | 2 × 6 (`ref.space.25` × `ref.space.75`) | 10 / Semibold (`sys.typo.caption`) |
+
+`ref.space.25` (2px) and `ref.space.75` (6px) bind raw because `sys.*` exposes no steps there — in lockstep with [Update](./update.md)'s rungs.
+
+## States
+
+Presentational — no hover, pressed, focused, or disabled. State belongs to the host row; a disabled host may suppress the badge rather than dim it.

package/agents/components/badge/role.spec.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Badge",
+  "family": "badge",
+  "subcomponent": "role",
+  "description": "Role badge — a tonal primary-container pill naming a user's role or title, riding the bare nickname (no @ prefix) at the end of the user-metadata meta row. Labels display in English; canonical: 'Channel owner' (채널장), 'Verified' (현직자, the verified professional). Two appearances: `default` (pale `sys.color.primaryContainer` fill with `sys.color.onPrimaryContainer` label) and `inverse` (`sys.color.inverseSurface` / `sys.color.inverseOnSurface` — reserved for the PRO mark on paid professional users). Shared geometry, 10px (`caption`) text, 16-rung min-height, `radius.full` corner. Identity, not state: it says who the person *is* — for workflow state (pending / rejected / draft) reach for StatusTag instead. Presentational; never interactive. Reaches the meta row through Metadata's meta-item `badge` field so the pill renders outside the nickname's <a>.",
+  "element": "span",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "role"
+    },
+    "appearance": {
+      "type": "literal",
+      "values": [
+        "default",
+        "inverse"
+      ],
+      "default": "default",
+      "description": "`default` — tonal primaryContainer pair for ordinary role marks (Channel owner, Verified). `inverse` — high-contrast inverseSurface pair, reserved for the paid-expert PRO mark."
+    },
+    "children": {
+      "type": "node",
+      "description": "Required role / title label — short, single line, English display (Channel owner, Verified, Moderator)."
+    }
+  },
+  "slots": {
+    "label": {
+      "required": true,
+      "description": "The role / title text — English display, 1–2 words; the pill grows with content from the 16px square minimum.",
+      "accepts": [
+        "text"
+      ]
+    }
+  },
+  "appearances": {
+    "default": {
+      "background": "sys.color.primaryContainer",
+      "label": "sys.color.onPrimaryContainer",
+      "radius": "sys.radius.full",
+      "default": true,
+      "note": "Tonal informational pair — pale primary container fill with the deep primary-container label. Theme-aware sys tokens, so no separate dark binding. Never the brand pair: brand is reserved for the Update sub's activity marker, and a brand-filled role mark would read as an alert, not an identity."
+    },
+    "inverse": {
+      "background": "sys.color.inverseSurface",
+      "label": "sys.color.inverseOnSurface",
+      "radius": "sys.radius.full",
+      "note": "Inverse pair — the strongest mark in the row: near-black pill with light label (theme-aware; flips in dark mode). Reserved for the PRO mark on paid professional users. Same geometry as default; only the fill pair changes."
+    }
+  },
+  "sizes": {
+    "medium": {
+      "minHeight": "ref.space.200",
+      "minWidth": "ref.space.200",
+      "paddingBlock": "ref.space.25",
+      "paddingInline": "ref.space.75",
+      "labelTypo": "sys.typo.caption",
+      "labelLineHeight": "1.2",
+      "note": "Single 16-rung (`ref.space.200`) — sized to ride inline beside `caption`/`label` metadata text without stretching the row. 2 × 6 padding (`ref.space.25` × `ref.space.75`); the reference steps bind raw where `sys.*` exposes no step, in lockstep with the Update sub's rungs. Label line-height is the structural `1.2` (same device as StatusTag): 10px × 1.2 + 2 × 2px padding = exactly 16px — `caption`'s 15px running-text line would push the pill to 19."
+    }
+  },
+  "accessibility": {
+    "announcement": "The label is real text and announces as-is (e.g. 'Verified'). No extra aria-label needed when the visible text already names the role; do not aria-hide it — the role mark carries meaning the surrounding metadata does not repeat."
+  },
+  "forbidden": [
+    "role badge used for workflow state (pending / approved / rejected / draft) — that is StatusTag's contract",
+    "role badge used for unread / new-activity signalling — that is the Update sub (brand fill)",
+    "brand or error fill on a role badge — the role mark is informational, only the primaryContainer pair",
+    "interactive usage (onClick, href, hover affordance) — presentational, state belongs to the host row",
+    "more than one badge on a nickname — exactly one role badge may ride the nickname; when a user qualifies for several, pick the contextually dominant one",
+    "role badge detached from a user identity host — canonical seat is the bare nickname at the end of the Metadata meta row (via the meta item's `badge` field, outside the link); it annotates a person, never floats alone",
+    "role badge placed inside the nickname <a> (link content) — pass it through the meta item's `badge` field so it stays outside the link",
+    "inverse appearance on a non-PRO mark — the high-contrast pair is the paid-expert signal, not a styling option"
+  ]
+}

package/agents/components/badge/update.md

@@ -0,0 +1,132 @@
+# Update
+
+A small brand-tone indicator attached to a host label — flagging *new or unread activity*. Two types share the brand fill and `radius.full` corner: **Numeric** (a labelled count pill) and **Dot** (a labelless update dot used by [Thumbnail](../thumbnail/thumbnail.md)). Always anchored to a host; never interactive.
+
+**Reach for Numeric when** the count itself carries meaning — 3 unread, 12 mentions, `99+` notifications. **Reach for Dot when** the presence of activity is the whole signal — a corner flag without a magnitude. **Skip Update** when the mark names *who the person is* rather than *what is new* — use [Role](./role.md) — or when it is descriptive metadata — use [Tag](../chip/tag.md).
+
+**Layout inset.** inline — slot atom. Lives anchored to a host (Thumbnail corner, List row label, icon glyph); the host places it. Never a sibling of `full-bleed` page rows.
+
+## Numeric
+
+A short count next to its host label. Two rungs (`medium` / `small`); a 1-character label collapses to a circle, 2 characters or `99+` stretches into a pill. `count` applies the `99+` cap automatically; pass `children` for non-numeric labels (`NEW`).
+
+```preview
+badge/update/default
+---
+import { Badge } from '@teamblind-chorus/ui';
+
+<Badge>3</Badge>
+```
+
+## Dot
+
+The labelless form — a corner activity flag. Two rungs (`dot-md` 8 × 8, `dot-sm` 6 × 6); brand fill with a 2px (`borderWidth.thin`) `surface`-color outline (`box-shadow`) so the dot stays discrete without enlarging its bounding box. Dot rungs ignore `count` and `children`. [Thumbnail](../thumbnail/thumbnail.md) is the canonical host — `dot-md` at 32 / 40 / 48, `dot-sm` at 16 / 20 / 24.
+
+```preview
+badge/update/dot
+---
+import { Badge } from '@teamblind-chorus/ui';
+
+<Badge size="dot-md" />
+```
+
+## Use cases
+
+### Digit cases
+
+Single digit collapses to a circle (`min-width = min-height`); two digits stretch via `padding-inline`; counts past 99 cap at `99+`.
+
+```preview
+badge/update/digit-cases
+---
+import { Badge } from '@teamblind-chorus/ui';
+
+<div style={{ display: 'flex', alignItems: 'center', gap: 'var(--sys-layout-inline-lg)' }}>
+  <Badge count={3} />
+  <Badge count={27} />
+  <Badge count={142} />
+</div>
+```
+
+### On thumbnail
+
+The canonical hosted form — Dot at a [Thumbnail](../thumbnail/thumbnail.md)'s top-right. Thumbnail picks `dot-md` at 32 / 40 / 48 and `dot-sm` at 16 / 20 / 24. The dot rides above the image without enlarging the bounding box.
+
+```preview
+badge/update/on-thumbnail
+---
+import { Thumbnail } from '@teamblind-chorus/ui';
+
+<Thumbnail size={48} src="…" alt="Channel" updateDot />
+```
+
+### On icon
+
+Dot painted at an icon's top-right (notification bell, chat, mention). Always `dot-sm` regardless of icon size — a 6 × 6 dot reads as a highlight against the icon's drawing area. The 2px `surface`-color outline keeps it discrete from the icon stroke; the icon's `icon.md` / `icon.lg` footprint never changes.
+
+```preview
+badge/update/on-icon
+---
+import { Badge } from '@teamblind-chorus/ui';
+import { BellIcon } from '@teamblind-chorus/ui/icons';
+
+<span style={{ position: 'relative', display: 'inline-flex' }}>
+  <BellIcon size={24} />
+  <Badge size="dot-sm" style={{ position: 'absolute', top: 0, right: 0, transform: 'translate(25%, -25%)' }} />
+</span>
+```
+
+### With host
+
+Numeric badge attached inside the label cell of a thumbnail `List` row — the canonical product use. Badge sits flush against the channel name (8px inline gap).
+
+```preview
+badge/update/with-host
+---
+import { Badge, List } from '@teamblind-chorus/ui';
+
+const labelWithBadge = (text, count) => (
+  <span style={{ display: 'inline-flex', alignItems: 'center', gap: 'var(--sys-layout-inline-md)', minWidth: 0 }}>
+    <span style={{ overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>{text}</span>
+    <Badge count={count} />
+  </span>
+);
+
+<List
+  variant="standard"
+  items={[
+    { value: 'amazon',  label: labelWithBadge('Amazon',  142), supportingText: 'Private · My company', thumbnail: { src: '/amazon.png',  alt: 'Amazon' } },
+    { value: 'samsung', label: labelWithBadge('Samsung',  27), supportingText: 'Private · My company', thumbnail: { src: '/samsung.png', alt: 'Samsung' } },
+    { value: 'naver',   label: labelWithBadge('Naver',     3), supportingText: 'Public · Tech',        thumbnail: { src: '/naver.png',   alt: 'Naver' } },
+  ]}
+/>
+```
+
+## Appearance
+
+Single appearance — the **brand** token pair (`sys.color.brand` background, `sys.color.onBrand` label). Brand is one tonal step brighter than `error` and reserved for short-label attention pins. Do not reach for `error` or `brandContainer`.
+
+## Slots
+
+- **label** *(Numeric only)* — the count. Required on Numeric, single line; `99+` cap once count crosses 99. Non-numeric labels (`NEW`) allowed. Dot carries no label slot.
+
+## Sizes
+
+Four rungs split across the two types — two per type. All rungs share `sys.radius.full` (9999px) corners.
+
+| Type     | Size    | Min-height / width       | Padding (block × inline)                 | Label                                | Halo                       |
+|----------|---------|--------------------------|------------------------------------------|--------------------------------------|----------------------------|
+| Numeric  | medium  | 20px (`ref.space.250` ‡) | 0 × 6 (`0` × `ref.space.75` ‡)           | 12 / Semibold (`sys.typo.label.sm`)  | —                          |
+| Numeric  | small   | 16px (`ref.space.200`)   | 0 × 4 (`0` × `sys.layout.container.2xs`) | 10 / Semibold (`sys.typo.caption`) | —                          |
+| Dot      | dot-md  | 8px (`ref.space.100`)    | 0 × 0                                    | — (labelless)                        | 2px `sys.color.surface` ⁋  |
+| Dot      | dot-sm  | 6px (`ref.space.75`)     | 0 × 0                                    | — (labelless)                        | 2px `sys.color.surface` ⁋  |
+
+‡ `ref.space.250` (20px) and `ref.space.75` (6px) bind raw because `sys.*` does not expose those steps. Dot rungs reuse `ref.space.100` (8px) and `ref.space.75` (6px) in lockstep with [Thumbnail's update-dot ladder](../thumbnail/thumbnail.md#sizes).
+
+⁋ Dot outline is a `box-shadow` so the bounding footprint never changes when the dot sits on a host image.
+
+`min-width = min-height` + `radius.full` guarantees a perfect circle for one character (or labelless dot) and a content-growing pill otherwise.
+
+## States
+
+Presentational — no hover, pressed, focused, or disabled. State belongs to the host. Disabled hosts may suppress the badge entirely rather than dim it.

package/agents/components/badge/update.spec.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Badge",
+  "family": "badge",
+  "subcomponent": "update",
+  "description": "Brand-tone indicator attached to a host label (channel entry, list row, thumbnail corner) flagging unread / new activity. Two top-level **types** share the same brand fill and `radius.full` corner: **Numeric** (a labelled count pill, the canonical badge — `size: medium | small`) and **Dot** (a labelless update dot — `size: dot-md | dot-sm` — used by [Thumbnail](../thumbnail/thumbnail.md) as the corner activity flag, and reachable by any other host that wants the same affordance). The Dot rungs ignore `count` and `children` and never render text.",
+  "element": "span",
+  "types": {
+    "numeric": {
+      "description": "Labelled count pill — the canonical Badge form. A 1-character label collapses to a perfect circle; 2+ characters or `99+` stretch into a content-growing pill.",
+      "sizes": [
+        "medium",
+        "small"
+      ]
+    },
+    "dot": {
+      "description": "Labelless update dot — the corner activity flag. Paints a 1px `surface`-color halo as `box-shadow` so it reads cleanly above any host imagery without enlarging its bounding box.",
+      "sizes": [
+        "dot-md",
+        "dot-sm"
+      ]
+    }
+  },
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "update"
+    },
+    "size": {
+      "type": "literal",
+      "values": [
+        "medium",
+        "small",
+        "dot-md",
+        "dot-sm"
+      ],
+      "default": "medium",
+      "description": "Four rungs split across the two types. **Numeric** — `medium` / `small` carry the count label. **Dot** — `dot-md` (8×8) / `dot-sm` (6×6) drop the label entirely and paint the labelless update dot. The dot rungs ignore `count` and `children`."
+    },
+    "count": {
+      "type": "number",
+      "optional": true,
+      "description": "Numeric type only. If provided, the badge formats the value: 1–99 render as the literal number, 100+ renders as `99+`. Pass children instead for non-numeric content (e.g. `NEW`). Ignored on the Dot rungs."
+    },
+    "children": {
+      "type": "node",
+      "optional": true,
+      "description": "Numeric type only — custom label, overrides count formatting. Ignored on the Dot rungs."
+    }
+  },
+  "slots": {
+    "label": {
+      "required": false,
+      "description": "Short single-line label — typically a 1–2 digit count or the literal `99+` overflow. Required on the Numeric rungs (`medium` / `small`); absent on the Dot rungs (`dot-md` / `dot-sm`).",
+      "accepts": [
+        "text"
+      ]
+    }
+  },
+  "appearance": {
+    "background": "sys.color.brand",
+    "label": "sys.color.onBrand",
+    "radius": "sys.radius.full",
+    "dotOutline": {
+      "color": "sys.color.surface",
+      "width": "sys.borderWidth.thin",
+      "rendering": "box-shadow",
+      "note": "Update Dot rungs paint a 2px `surface`-color outline as a `box-shadow` so the dot stays a discrete chip on any host (image, icon, row) without enlarging its bounding box. The outline carves the dot out of whatever sits beside it; without it the brand fill blends into surrounding fills with similar luminance."
+    }
+  },
+  "sizes": {
+    "medium": {
+      "minHeight": "ref.space.250",
+      "minWidth": "ref.space.250",
+      "paddingBlock": "0",
+      "paddingInline": "ref.space.75",
+      "labelTypo": "sys.typo.label.sm"
+    },
+    "small": {
+      "minHeight": "ref.space.200",
+      "minWidth": "ref.space.200",
+      "paddingBlock": "0",
+      "paddingInline": "sys.layout.container.2xs",
+      "labelTypo": "sys.typo.caption"
+    },
+    "dot-md": {
+      "minHeight": "ref.space.100",
+      "minWidth": "ref.space.100",
+      "paddingBlock": "0",
+      "paddingInline": "0",
+      "labelTypo": null,
+      "note": "Labelless 8 × 8 dot (`ref.space.100`) — Thumbnail's update flag at the 32 / 40 / 48 rungs. Paints the brand fill with a 1px `surface`-color halo so it carves out of the host image."
+    },
+    "dot-sm": {
+      "minHeight": "ref.space.75",
+      "minWidth": "ref.space.75",
+      "paddingBlock": "0",
+      "paddingInline": "0",
+      "labelTypo": null,
+      "note": "Labelless 6 × 6 dot (`ref.space.75`) — Thumbnail's update flag at the 16 / 20 / 24 rungs."
+    }
+  },
+  "accessibility": {
+    "announcement": "A badge conveys meaning (unread count / new activity) that colour and position alone do not expose. The Numeric badge MUST carry an accessible name that states what the number means — e.g. aria-label='5 unread', not the bare '5' — supplied via aria-label on the badge or visually-hidden text in the host label. A lone number is meaningless to a screen reader.",
+    "dot": "The labelless Dot has no text at all. It MUST be given an accessible name on the host (e.g. aria-label='New activity'), OR — when the host's own label already announces the unread / new state — the dot carries aria-hidden='true' to avoid a meaningless duplicate announcement.",
+    "overflow": "When the count overflows to '99+', the accessible name should read the intent (e.g. 'over 99 unread'), not the literal glyph."
+  },
+  "forbidden": [
+    "badge painted with sys.color.brand outside the HOT / NEW / unread-count canon — brand on a badge is the marker, not a tint",
+    "badge rendered as a raw <span> with Tailwind — badge chrome owns the radius / padding / typography",
+    "more than one badge on the same anchor — the host slot is single-badge by anatomy",
+    "badge label below 12px (label.sm is the floor)"
+  ]
+}

package/agents/components/banner/banner.family.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "banner",
+  "name": "Banner",
+  "description": "Inline notice surface \u2014 a tonal aside that highlights supplementary context inside the content column. Two tones: `accent` (primary-tinted, worth pulling the eye to) and `default` (quiet `secondaryContainer`, supplementary). Single-spec family.",
+  "useCases": [
+    "inline notice",
+    "supplementary context",
+    "tonal aside",
+    "in-flow tip"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "inline",
+  "wrapperGuidance": "Inline card. Banner has its own internal padding + border-radius + tinted fill, but it ships no outer margin and does NOT claim the page rail. The host owns the surrounding inset: when placed at the page-shell level, the shell's `layout.page.md` gutter provides the 16px horizontal safe zone; when wrapped inside another host (Section body, Feed card, BottomSheet content slot, SideSheet column), that host's container padding governs the inset. Vertical 8px between Banner and its siblings is paid by the parent column as `gap: var(--sys-layout-stack-xs)` \u2014 never paint per-child `margin-block` on Banner. As an inline atom, Banner fits any container that lays out children in a column.",
+  "spec": "banner.md",
+  "usage": {
+    "note": "Body text is children, not a `body` prop; `action` is an object with `label` + `href`/`onClick`.",
+    "example": "<Banner appearance=\"default\" action={{ label, href }}>…</Banner>"
+  },
+  "subcomponents": [
+    {
+      "slug": "banner",
+      "spec": "banner.spec.json",
+      "md": "banner.md",
+      "default": true
+    }
+  ]
+}

package/agents/components/banner/banner.md

@@ -0,0 +1,136 @@
+# Banner
+
+An in-body explanation block — a tinted card sitting within the reading flow with a short paragraph and an optional follow-through link. Two axes: **appearance** (`default` / `accent` / `destructive`), **leading slot** (`icon` / `thumbnail` / none).
+
+**Reach for this when** a passage needs a brief aside the reader can scan or skip. **Skip when** the message demands a decision ([Dialog](../dialog/dialog.md) / [Bottom sheet](../bottom-sheet/bottom-sheet.md)) or confirms a recent user action ([Toast](../toast/toast.md)).
+
+**Layout inset.** inline — Banner is an inline card. It owns internal padding (`sys.layout.container.sm`), corner (`sys.radius.md`), and tinted fill, but ships **no outer margin** and does not claim the page rail. The host pays surrounding horizontal inset — page shell `layout.page.md` at the top level, or a wrapping host's container padding inside `<Carousel>` / `<Feed>` / `<BottomSheet>` / `<SideSheet>`. Vertical 8 is paid by the parent as `gap: var(--sys-layout-stack-xs)` on the column hosting Banner and its siblings. Never wrap Banner in a `padding-block` div or re-wrap in `<Carousel>` for spacing — one parent, one `gap`. See [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+The muted appearance — body in `onSecondaryContainer`, action link in `primary`. Supplementary asides the reader can pass over without missing the main flow.
+
+```preview
+banner/default
+---
+import { Banner } from '@teamblind-chorus/ui';
+
+<Banner
+  appearance="default"
+  action={{ label: 'How levels work', href: '#level' }}
+>
+  Stay active in the community to level up and unlock more of what the app offers.
+</Banner>
+```
+
+## Use cases
+
+### Accent
+
+The primary-tinted appearance. Body and action both paint in the primary family — reach for it when the aside should pull more attention.
+
+```preview
+banner/accent
+---
+import { Banner } from '@teamblind-chorus/ui';
+
+<Banner
+  appearance="accent"
+  action={{ label: 'How levels work', href: '#level' }}
+>
+  Stay active in the community to level up and unlock more of what the app offers.
+</Banner>
+```
+
+### Destructive
+
+The error-tinted appearance — `errorContainer` fill with `onErrorContainer` foreground. Reach for it when the aside is a blocking error or rejection (failed approvals, integration outages, billing). Use sparingly.
+
+```preview
+banner/destructive
+---
+import { Banner } from '@teamblind-chorus/ui';
+
+<Banner
+  appearance="destructive"
+  action={{ label: 'Retry connection', onClick: () => {} }}
+>
+  We could not reach the integrations service. Recent changes have not been synced.
+</Banner>
+```
+
+### With thumbnail
+
+A leading [Thumbnail](../thumbnail/thumbnail.md) at the top-left — reach for it when the aside is anchored to a channel, author, or sub-brand image. Thumbnail owns its diameter and corner shape; the slot only top-aligns it next to the content column.
+
+```preview
+banner/with-thumbnail
+---
+import { Banner, Thumbnail } from '@teamblind-chorus/ui';
+
+<Banner
+  appearance="accent"
+  thumbnail={<Thumbnail size={40} alt="Channel" src="/channel.png" />}
+  action={{ label: 'How levels work', href: '#level' }}
+>
+  Stay active in the community to level up and unlock more of what the app offers.
+</Banner>
+```
+
+### With icon
+
+A 16 × 16 (`sys.icon.md`) glyph at the leading edge, painted in `currentColor`. The slot is sized to the body's first-line height so the glyph centres on the first line — multi-line bodies keep the icon anchored to the first-line cap, not the block centre. Reach for it when the aside leads with a meaning-bearing glyph rather than a brand image.
+
+```preview
+banner/with-icon
+---
+import { Banner } from '@teamblind-chorus/ui';
+import { StarIcon } from '@teamblind-chorus/ui/icons';
+
+<Banner
+  appearance="accent"
+  icon={<StarIcon size={16} />}
+  action={{ label: 'How levels work', href: '#level' }}
+>
+  Stay active in the community to level up and unlock more of what the app offers.
+</Banner>
+```
+
+## Appearance
+
+Two appearances on the *emphasis* axis (plus `destructive` for errors). Banner carries no disabled state; only the optional action link follows the link state contract.
+
+| Appearance    | Container fill                                                                              | Body / action color                                                | When to use                                                                  |
+|---------------|---------------------------------------------------------------------------------------------|--------------------------------------------------------------------|------------------------------------------------------------------------------|
+| `default`     | `sys.color.scrimSubtle` (translucent inverse-tone scrim — ~8% black light / ~8% white dark) | body in `sys.color.onSurface`, action steps to `sys.color.primary` | Supplementary asides the reader can pass over without missing the main flow. |
+| `accent`      | `sys.color.primaryContainer`                                                                | body in `onPrimaryContainer`, action inherits                      | Asides worth pulling the eye toward — new-feature explainers, capability nudges. |
+| `destructive` | `sys.color.errorContainer`                                                                  | body in `onErrorContainer`, action inherits                        | Blocking errors or rejections — failed approvals, outages, billing.          |
+
+## Slots
+
+- **container** — tinted block. Horizontal flex with `align-items: flex-start`; 12px inset, 8px sibling gap, 8px corner radius.
+- **icon** *(optional)* — 16 × 16 glyph. Slot height equals the `body.sm` line box so the glyph centres on the body's first line. Paints in `currentColor`.
+- **thumbnail** *(optional)* — leading [Thumbnail](../thumbnail/thumbnail.md). Takes precedence over `icon`; footprint and corner come from Thumbnail.
+- **content** — vertical column holding body and optional action; 8px stack gap; fills remaining inline space.
+- **body** — explanation copy. `body.sm` / Regular / inherits container foreground. Required.
+- **action** *(optional)* — follow-through link below the body. `label.md` / Semibold / underlined.
+
+## Anatomy
+
+| Slot      | Token bindings |
+|-----------|----------------|
+| container | Fill + foreground per appearance, `sys.radius.md` (8), `sys.layout.container.sm` (12) padding, `sys.layout.stack.xs` (8) sibling gap, `align-items: flex-start` |
+| icon      | `sys.icon.md` (16 × 16) glyph inside a slot whose height equals the body's first-line box (`calc(sys.typo.body.sm.size * sys.typo.body.sm.line)`); `color: currentColor` |
+| thumbnail | Delegated to [Thumbnail](../thumbnail/thumbnail.md); footprint-preserving (`flex: 0 0 auto`) |
+| content   | Flex column, `flex: 1 1 auto`, `sys.layout.stack.xs` (8) body↔action gap |
+| body      | `sys.typo.body.sm` (14 / Regular), color inherits |
+| action    | `sys.typo.label.md` (14 / Semibold), underlined. Steps to `sys.color.primary` in `default`; inherits in `accent` / `destructive`. |
+
+## States
+
+Container carries no interactive state. The action link follows the standard link state contract — hover underline persists, pressed darkens.
+
+## Behavior
+
+- **Action link.** Renders as `<a>` accepting `href` or `onClick`. Underline persists at rest so the link reads as actionable inside the muted block.
+- **Block role.** Container carries `role="note"`.