@teamblind-chorus/ui 1.0.0

package/agents/components/tabs/underline.md

@@ -0,0 +1,147 @@
+# Underline
+
+The canonical content-section switcher — a row of tabs anchored above a panel, with a 2px `onSurface` indicator that slides along the active tab's bottom edge.
+
+**Reach for this when** moving between peer panels of the same surface. **Skip when** the row is an in-place mode change — use [Segmented](./segmented.md) instead.
+
+**Layout inset.** full-bleed — edge-to-edge family. Sits as a direct child of the page shell so the indicator travels between page edges; the row pays its own 16px inline padding via `layout.container.*` — do **not** wrap it in another padding div, or the page rail double-pays. Inside a bounded surface (Card / Dialog / BottomSheet / Sheet), apply the negative-margin opt-out — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+## Default
+
+Headline form — three peer panels switched by a tab row. Adaptive width (see [Behavior](#behavior)).
+
+```preview
+tabs/underline/default
+---
+import { Tabs, Tab } from '@teamblind-chorus/ui';
+
+<Tabs variant="underline" value="overview" aria-label="Sections">
+  <Tab value="overview">Overview</Tab>
+  <Tab value="props">Props</Tab>
+  <Tab value="examples">Examples</Tab>
+</Tabs>
+```
+
+## Use cases
+
+### With icon
+
+A leading glyph before the label.
+
+```preview
+tabs/underline/leading-icon
+---
+import { Tabs, Tab } from '@teamblind-chorus/ui';
+import { PlusIcon, CheckedIcon } from '@teamblind-chorus/ui/icons';
+
+<Tabs variant="underline" value="posts" aria-label="Profile sections">
+  <Tab value="posts" leadingIcon={<PlusIcon />}>Posts</Tab>
+  <Tab value="replies">Replies</Tab>
+  <Tab value="likes" leadingIcon={<CheckedIcon />}>Likes</Tab>
+</Tabs>
+```
+
+### Auto-fit
+
+Wider terminal layout of Adaptive width — tabs share row width equally; indicator widens to match.
+
+```preview
+tabs/underline/auto-fit
+---
+import { Tabs, Tab } from '@teamblind-chorus/ui';
+
+<Tabs variant="underline" value="feed" aria-label="Sections">
+  <Tab value="feed">Feed</Tab>
+  <Tab value="channels">Channels</Tab>
+  <Tab value="members">Members</Tab>
+</Tabs>
+```
+
+### Overflow
+
+Narrower terminal layout — tabs hold content width and the row scrolls. The trailing 48px (`ref.space.600`) paints as a transparent `mask-image` edge fade; clears when scrolled to the last tab.
+
+```preview
+tabs/underline/overflow
+---
+import { Tabs, Tab } from '@teamblind-chorus/ui';
+
+<Tabs variant="underline" value="overview" aria-label="Sections">
+  <Tab value="overview">Overview</Tab>
+  <Tab value="props">Props</Tab>
+  <Tab value="examples">Examples</Tab>
+  <Tab value="accessibility">Accessibility</Tab>
+  <Tab value="changelog">Changelog</Tab>
+  <Tab value="related">Related components</Tab>
+  <Tab value="discussion">Discussion</Tab>
+</Tabs>
+```
+
+### Focus indicator
+
+Static specimen — pins the keyboard-focus ring to the selected tab. See top-level [Focus indicator](#focus-indicator).
+
+```preview
+tabs/underline/focused
+---
+import { Tabs, Tab } from '@teamblind-chorus/ui';
+
+<Tabs variant="underline" value="posts" aria-label="Profile">
+  <Tab value="posts" state="focused">Posts</Tab>
+  <Tab value="replies">Replies</Tab>
+  <Tab value="likes">Likes</Tab>
+</Tabs>
+```
+
+## Slots
+
+- **label** — tab's accessible name. Required, single line.
+- **leadingIcon** (optional) — context glyph sized at `sys.icon.md` (16) before the label.
+
+## Anatomy
+
+| Prop / state           | Container          | Label color                           | Indicator                         |
+|------------------------|--------------------|---------------------------------------|-----------------------------------|
+| **Tab — unselected**   | transparent        | `sys.color.outline` (muted foreground) | none                  |
+| **Tab — selected**     | transparent        | `sys.color.onSurface` (strong foreground) | 2px `sys.borderWidth.thin` × `sys.color.onSurface` along the bottom edge |
+| **Container row**      | transparent, 16px inline padding, 1px `sys.color.outlineVariant` bottom divider running the full row width. Selected indicator paints over this divider. Edge fade (rightmost 48px / `ref.space.600`) paints via `mask-image` only while overflow is present. | — | — |
+
+## Sizes
+
+A single fixed rung — the 40px footprint stays constant across breakpoints.
+
+| Property                          | Value                | Token                              |
+|-----------------------------------|----------------------|-------------------------------------|
+| Container padding (inline)        | 16px                 | `sys.layout.container.md`          |
+| Min-height (per tab)              | 40px                 | `ref.space.500` ‡                  |
+| Padding (block × inline)          | 8 × 16               | `sys.layout.container.xs` × `sys.layout.container.md` |
+| Inter-tab gap                     | 0                    | — †                                |
+| Slot gap (icon ↔ label)           | 4px                  | `sys.layout.inline.sm`             |
+| Indicator height                  | 2px                  | `sys.borderWidth.thin`              |
+| Container bottom divider          | 1px                  | `sys.borderWidth.hairline` × `sys.color.outlineVariant` |
+| Label                             | 14 / Semibold        | `sys.typo.label.md`                |
+| Icon                              | 16px                 | `sys.icon.md`                      |
+| Edge fade width                   | 48px                 | `ref.space.600` — trailing `mask-image`, on overflow only |
+
+‡ `min-height` binds raw `ref.space.*` — `sys.*` does not currently expose a 40px step.
+
+† Adjacent tabs sit flush; the visible 32px breathing comes from each tab's 16px inline padding on both sides.
+
+## States
+
+| State      | Overlay opacity            | Additional                                                                 |
+|------------|----------------------------|-----------------------------------------------------------------------------|
+| `default`  | —                          | Container + label at rest.                                                  |
+| `hovered`  | `sys.state.hover` (8%)     | Pointer-driven via `:hover`.                                                |
+| `pressed`  | `sys.state.pressed` (16%)  | Pointer-driven via `:active`.                                               |
+| `selected` | —                          | Label flips to `sys.color.onSurface`; 2px indicator slides to the new tab.   |
+| `disabled` | overlay suppressed         | Label at `sys.state.disabled` (40%) opacity, focus ring suppressed, `cursor: not-allowed`. |
+
+## Focus indicator
+
+**Composition: Inward** — row is a horizontal scroller, so an outward ring would clip. Paints as inset shadows inside the tab's bounding box on a `::after` overlay above the state-overlay tint and underline indicator. Focus never shifts a tab. Trigger: `:focus-visible`. See [Focus ring composition](../../DESIGN.md#focus-ring-composition).
+
+## Behavior
+
+- **Adaptive width.** One width mode — the row measures intrinsic tab widths against the container on every layout pass via `ResizeObserver`. If `Σ tab.intrinsicWidth ≤ container.clientWidth`, tabs share width equally (`flex: 1 1 0`) and the indicator widens to match; otherwise tabs hold content width (`flex: 0 0 auto`) and the row scrolls with the trailing edge fade. Mode flip is layout-immediate (no animation). No `fullWidth` prop — caller sizes the container; row picks Fit on its own.
+- **Sliding indicator.** One indicator in the row, not one per tab. Selecting a different tab slides the 2px (`sys.borderWidth.thin`) stroke into the new tab's `offsetLeft` / `offsetWidth` over 220ms — reads as a single continuous gesture. The indicator scrolls with the row so it stays glued to its tab; on first paint the slide is suppressed; when Adaptive width flips between Fit and Scroll, the indicator's width is re-measured.

package/agents/components/tabs/underline.spec.json

@@ -0,0 +1,139 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Tabs",
+  "family": "tabs",
+  "subcomponent": "underline",
+  "description": "Horizontal tab row with a single 2px (`sys.borderWidth.thin`) `sys.color.onSurface` indicator that slides between the active tab's bottom edge on selection. Default content-section switcher.",
+  "element": "div",
+  "props": {
+    "variant": {
+      "type": "literal",
+      "value": "underline"
+    },
+    "value": {
+      "type": "string",
+      "description": "The active tab's value."
+    },
+    "onChange": {
+      "type": "function",
+      "description": "Fired with the next value when a tab is selected."
+    },
+    "aria-label": {
+      "type": "string",
+      "description": "Accessible name for the tablist."
+    },
+    "embedded": {
+      "type": "boolean",
+      "default": false,
+      "description": "Composition mode flag. When `true` (or when Tabs is a direct child of `.chorus-carousel` / `.chorus-feed`), enters **embedded mode**: zeroes its own `background` + `padding` so chrome defers to the host. Pass explicitly inside `<Carousel>` / `<Feed>` for the contract to be visible in JSX; the DOM-ancestry safety net in styles.css also activates the mode when omitted. See `compositionModes` in `tabs.family.json`."
+    }
+  },
+  "behavior": {
+    "adaptiveWidth": {
+      "description": "Row measures Σ(tab.intrinsicWidth) vs container.clientWidth on every layout pass. Fits → tabs stretch (flex: 1 1 0); exceeds → tabs hold content width (flex: 0 0 auto) and the row scrolls horizontally with a trailing Edge fade. Re-evaluated via ResizeObserver on container + tab row. Not a caller-supplied prop."
+    }
+  },
+  "tabProps": {
+    "value": {
+      "type": "string",
+      "required": true
+    },
+    "leadingIcon": {
+      "type": "node",
+      "optional": true
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "slots": {
+    "label": {
+      "required": true,
+      "description": "Tab's accessible name. Single line.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "leadingIcon": {
+      "required": false,
+      "description": "Context glyph before label.",
+      "accepts": [
+        "icon"
+      ]
+    }
+  },
+  "sizing": {
+    "minHeight": "ref.space.500",
+    "containerPaddingInline": "sys.layout.container.md",
+    "paddingBlock": "sys.layout.container.xs",
+    "paddingInline": "sys.layout.container.md",
+    "interTabGap": "0",
+    "slotGap": "sys.layout.inline.sm",
+    "indicatorHeight": "sys.borderWidth.thin",
+    "dividerWidth": "sys.borderWidth.hairline",
+    "dividerColor": "sys.color.outlineVariant",
+    "labelTypo": "sys.typo.label.md",
+    "iconSize": "sys.icon.md",
+    "fadeWidth": "ref.space.600"
+  },
+  "selectionStates": {
+    "unselected": {
+      "label": "sys.color.outline",
+      "indicator": null
+    },
+    "selected": {
+      "label": "sys.color.onSurface",
+      "indicator": "sys.color.onSurface"
+    }
+  },
+  "states": {
+    "default": {
+      "overlay": null
+    },
+    "hovered": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.hover"
+      }
+    },
+    "pressed": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.pressed"
+      }
+    },
+    "disabled": {
+      "overlay": null,
+      "containerOpacity": "sys.state.disabled",
+      "suppressFocusRing": true,
+      "cursor": "not-allowed"
+    }
+  },
+  "focusIndicator": {
+    "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the tab is in.",
+    "composition": "inward",
+    "compositionReason": "The Tabs row is a horizontal scroller (`overflow-x: auto`, which coerces `overflow-y: auto`), so an outward ring would clip at the row's top/bottom edges. Segmented and Rounded re-anchor the chip's ring the same way — their rows are scrollers too.",
+    "overlay": {
+      "color": "label",
+      "opacity": "sys.state.focus"
+    },
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "outerLayerPosition": "depth 0..2px from the tab edge (the outer stroke)",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset",
+      "insetLayerPosition": "depth 2..3px from the tab edge (the counter-ring just inside the outer stroke)",
+      "implementation": "inset box-shadow on the tab's `::after` overlay (sits above the state-overlay `::before`, the label/icon, and the underline indicator). Constrained strictly inside the tab's footprint and never exceeds it."
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "forbidden": [
+    "underline tabs given raw <button>/<a> or bare-text children instead of <Tab value=…> elements — the sliding indicator (.chorus-tabs__indicator), the useAdaptiveFit measurement that sets data-fit, the aria-selected/data-value binding, and the active label styling all live on <Tab>; raw children render as unstyled run-together text with no indicator and a broken scroll/stretch layout",
+    "active indicator painted with sys.color.brand — underline uses sys.color.onSurface for the indicator",
+    "tabs wrapped in extra horizontal padding — tabs is full-bleed by family declaration",
+    "tab label sizing below sys.typo.label.md (14px) — smaller text breaks Korean / CJK hierarchy",
+    "manual underline drawn via `border-bottom:` — indicator is the `::after` overlay, not a real border"
+  ]
+}

package/agents/components/thumbnail/thumbnail.family.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "thumbnail",
+  "name": "Thumbnail",
+  "description": "Image-bearing rectangle that surfaces alongside list rows, feed items, and channel headers. Single-spec family.",
+  "useCases": [
+    "avatar",
+    "channel image",
+    "list leading image",
+    "feed thumbnail",
+    "circular image"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "inline",
+  "spec": "thumbnail.md",
+  "usage": {
+    "note": "Pure circular image primitive (the channel/author avatar) — badges ride via the `updateDot` / `logoBadge` props, not children; carries no label of its own.",
+    "example": "<Thumbnail size={48} src=\"…\" alt=\"…\" />"
+  },
+  "subcomponents": [
+    {
+      "slug": "thumbnail",
+      "spec": "thumbnail.spec.json",
+      "md": "thumbnail.md",
+      "default": true
+    }
+  ]
+}

package/agents/components/thumbnail/thumbnail.md

@@ -0,0 +1,152 @@
+# Thumbnail
+
+A circular image — the unit that identifies a channel, a feed author, or any small-rung image. Two optional badges ride without changing footprint: an **update dot** top-right and a **logo badge** bottom-right. A pure visual primitive — no label of its own.
+
+**Reach for this when** the host needs to identify an entity at a glance — channel avatar in a list row, feed author block, AvatarRail item, NavigationBar leading. **Skip when** the surface is a labelled icon glyph (use [Icon Button](../button/icon.md)) or a sub-brand identity at fixed inline scale ([NavCard](../nav-card/nav-card.md)'s logo slot).
+
+**Layout inset.** inline — slot atom. Lives inside another component's leading slot (List row leading, Feed author block, AvatarRail item, SuggestionList row, NavigationBar leading); the host picks the rung (16 / 20 / 24 / 32 / 40 / 48 / 56) and places it. Never a sibling of `full-bleed` page rows.
+
+## Default
+
+Image only, no badges. Thumbnail is **image-first** — `src` expects a real image asset URL; the slot resolves to an `<img>`, not a glyph or text. When mocking up with no real image, fill `src` with `/placeholder.png` rather than omitting it — the empty-surface fallback is for runtime load failures, not design-time scaffolding.
+
+```preview
+thumbnail/default
+---
+import { Thumbnail } from '@teamblind-chorus/ui';
+
+<Thumbnail size={48} alt="Channel" src="/placeholder.png" />
+```
+
+## Use cases
+
+### With update dot
+
+A `brand`-tone dot at the top-right flags new activity. Decorative; the row carries the count in a sibling text slot.
+
+```preview
+thumbnail/with-update-dot
+---
+import { Thumbnail } from '@teamblind-chorus/ui';
+
+<Thumbnail size={48} alt="Channel" src="/placeholder.png" updateDot />
+```
+
+### With logo badge
+
+A 16 × 16 sub-brand mark at the bottom-right on its own surface halo.
+
+```preview
+thumbnail/with-logo-badge
+---
+import { Thumbnail } from '@teamblind-chorus/ui';
+
+<Thumbnail
+  size={48}
+  alt="Channel"
+  src="/placeholder.png"
+  logoBadge={{ src: '…', alt: 'Workspace' }}
+/>
+```
+
+### With both badges
+
+Top-right and bottom-right corners are independent and never collide.
+
+```preview
+thumbnail/with-both
+---
+import { Thumbnail } from '@teamblind-chorus/ui';
+
+<Thumbnail
+  size={48}
+  alt="Channel"
+  src="/placeholder.png"
+  updateDot
+  logoBadge={{ src: '…', alt: 'Workspace' }}
+/>
+```
+
+### With surface outline
+
+`outlined` paints a 2-token (`sys.borderWidth.thin`) `sys.color.surface` halo as an outset `box-shadow` around the container. The ring blends into the host's `surface*` tier and separates the circle's edge from anything visually noisy underneath. Painted as a shadow, not a `border:` — the rung's diameter never reflows.
+
+```preview
+thumbnail/with-outline
+---
+import { Thumbnail } from '@teamblind-chorus/ui';
+
+<Thumbnail size={56} alt="Channel" src="/placeholder.png" outlined />
+```
+
+**Reach for `outlined` when** the Thumbnail half-overlaps or sits over an image ([ProfileHeader](../profile-header/profile-header.md) avatar on cover, [Profile carousel](../carousel/profile.md) avatar on card cover), the backdrop is a brand-tonal strip or gradient ([Banner](../banner/banner.md) inside a colour-tinted host, a Section painted with a `*Container` fill), the Thumbnail sits over a dark photo / pattern / video frame, or two adjacent Thumbnails partially overlap (avatar stack, cluster).
+
+**Skip `outlined` when** the host is a plain `surface*` row (List / Feed / SuggestionList / Navigation bar leading) with no imagery underneath, the host's chrome already provides the separator (outlined card, hairline divider under the avatar), or the Thumbnail is `size={16}` / `size={20}` where the halo would dominate.
+
+The two corner badges (`updateDot`, `logoBadge`) carry their own 1-token surface halos and compose cleanly over the outlined ring — order is image → outlined ring → badge halos → badge fills, all painted as `box-shadow` so footprint never changes.
+
+### Size ladder
+
+The full ladder side-by-side; update-dot steps down at the 32-rung boundary.
+
+```preview
+thumbnail/size-ladder
+---
+import { Thumbnail } from '@teamblind-chorus/ui';
+
+<div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
+  <Thumbnail size={56} alt="A" updateDot />
+  <Thumbnail size={48} alt="B" updateDot />
+  <Thumbnail size={40} alt="C" updateDot />
+  <Thumbnail size={32} alt="D" updateDot />
+  <Thumbnail size={24} alt="E" updateDot />
+  <Thumbnail size={20} alt="F" updateDot />
+  <Thumbnail size={16} alt="G" updateDot />
+</div>
+```
+
+## Slots
+
+- **image** — required circular image at `radius.full`. When the asset hasn't loaded, the container holds `surfaceContainerHigh` and AT reads `alt`.
+- **updateDot** *(optional)* — `brand`-tone dot at the top-right. Decorative (`aria-hidden`); pair with a text affordance for the count. Rendered by [Badge](../badge/badge.md)'s `dot-md` / `dot-sm` rungs — `dot-md` at 32 / 40 / 48 / 56, `dot-sm` at 16 / 20 / 24.
+- **logoBadge** *(optional)* — 16 × 16 circular badge at the bottom-right, for a sub-brand glyph.
+
+Both corner overlays sit *above* the image and carry a 1px (`borderWidth.hairline`) `surface`-color halo as a `box-shadow` — no change to bounding footprint. With `outlined={true}` the container takes a 2px (`borderWidth.thin`) `surface`-color outset halo via `box-shadow`, composing cleanly with the two badge halos above.
+
+## Anatomy
+
+| Slot         | Token bindings |
+|--------------|----------------|
+| container    | `radius.full`, no fill of its own. With `outlined={true}` adds a 2px (`borderWidth.thin`) `surface`-color outset halo via `box-shadow` |
+| image        | `surfaceContainerHigh` fallback, `onSurfaceVariant` fallback glyph |
+| updateDot    | Rendered by [Badge](../badge/badge.md) `dot-md` / `dot-sm` (`brand` fill, `radius.full`, 2px `surface`-color outline); top-right flush |
+| logoBadge    | 16 × 16, `radius.full`, `surface` halo at 1px, bottom-right flush |
+
+## Sizes
+
+Seven rungs. Diameter binds to a raw `ref.space.*` step so Thumbnail can sit verbatim inside a fixed-footprint row.
+
+| Size  | Diameter | Update-dot | Logo badge | Token (diameter)            |
+|-------|----------|------------|------------|------------------------------|
+| 56    | 56px     | 8 × 8      | 16 × 16    | `ref.space.700`              |
+| 48    | 48px     | 8 × 8      | 16 × 16    | `ref.space.600`              |
+| 40    | 40px     | 8 × 8      | 16 × 16    | `ref.space.500`              |
+| 32    | 32px     | 8 × 8      | 16 × 16    | `ref.space.400`              |
+| 24    | 24px     | 6 × 6      | 16 × 16    | `ref.space.300`              |
+| 20    | 20px     | 6 × 6      | 16 × 16    | `ref.space.250`              |
+| 16    | 16px     | 6 × 6      | 16 × 16    | `ref.space.200`              |
+
+Update-dot steps down at 32 so it stays a *highlight*, not an *occluder*; logo badge pins at 16 because the glyph it carries is illegible below that. The 56 rung is reserved for the canonical follow-suggestion / xlarge directory-row leading slot (see [list/entry](../list/entry.md) `size="xlarge"`).
+
+## States
+
+Not interactive — no hover / pressed / focused / disabled. When wrapped in an interactive row, the row owns state and focus.
+
+When the image fails to load or `src` is omitted, the slot enters its **fallback** form — `/placeholder.png` paints as `background-image` (centered, covered) over a `surfaceContainerHigh` base. The fallback is a runtime safety net; design-time scaffolds should pass `/placeholder.png` through `src` explicitly.
+
+## Behavior
+
+- **Slot omission collapses without a gap.** Both badges drop out entirely when absent.
+- **Badges overlay; they never reflow the image.** Absolutely positioned; the 1px halo is a `box-shadow`.
+- **Image clipped to a perfect circle.** `radius.full` + `overflow: hidden`; hand in a square-or-larger source.
+- **Image fallback, not text fallback.** When `src` is omitted or the server fails to deliver, the slot's `background-image` paints `/placeholder.png` over a `surfaceContainerHigh` base. No text/initial fallback.

package/agents/components/thumbnail/thumbnail.spec.json

@@ -0,0 +1,172 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Thumbnail",
+  "family": "thumbnail",
+  "exportAlias": "Avatar",
+  "description": "Circular image — the unit used to identify a channel, a feed item's author, or any small-rung image that needs to live inside a denser composition (lists, feed rows, comment threads, mention rails). The image fills the whole footprint at full radius; two optional badges ride on the container without changing its footprint: an update dot at the top-right, and a logo badge at the bottom-right. A pure visual primitive — it never carries a label of its own.",
+  "element": "div",
+  "props": {
+    "size": {
+      "type": "enum",
+      "values": [
+        56,
+        48,
+        40,
+        32,
+        24,
+        20,
+        16
+      ],
+      "default": 48
+    },
+    "src": {
+      "type": "string",
+      "assetType": "image",
+      "optional": true,
+      "description": "URL of the image asset that fills the circular slot — a raster (PNG / JPG / WebP) or vector (SVG) source. Required for the rendered form; the prop is technically optional because the Thumbnail also has a defined `surfaceContainerHigh` fallback, but any production composition is expected to pass a real asset. When generating mock or scaffold compositions without a real channel / author image, use the bundled placeholder asset at `/placeholder.png` rather than omitting `src` — the empty-surface fallback is for runtime load failures, not for design-time scaffolding.",
+      "placeholder": "/placeholder.png",
+      "example": "/placeholder.png"
+    },
+    "alt": {
+      "type": "string",
+      "required": true
+    },
+    "updateDot": {
+      "type": "boolean",
+      "default": false
+    },
+    "logoBadge": {
+      "type": "object",
+      "optional": true,
+      "description": "{ src, alt } — 16×16 circular badge at the bottom-right."
+    },
+    "outlined": {
+      "type": "boolean",
+      "default": false,
+      "description": "When `true`, paints a 2-token-wide `sys.color.surface` outline around the Thumbnail container as an outset halo. The outline reads as an isolation ring that separates the Thumbnail's circular edge from anything visually noisy underneath it. Painted as `box-shadow: 0 0 0 sys.borderWidth.thin sys.color.surface` so it never reflows the slot's intrinsic diameter — same no-layout-stroke idiom the rest of the system uses. Pair with hosts whose chrome reads as a `surface*` tier (so the halo blends in) and whose backdrop differs from that tier (so the halo actually separates).",
+      "whenToReachForIt": [
+        "The Thumbnail half-overlaps or sits over an image — [ProfileHeader](../profile-header/profile-header.md) avatar (56-rung on cover band), [Profile carousel](../carousel/profile.md) avatar (64-rung on card cover), any avatar pulled onto a Hero / Cover photo.",
+        "The backdrop is a brand-tonal strip, a `*Container` fill, or a gradient band ([Banner](../banner/banner.md) inside a colour-tinted host, a Section painted with a `successContainer` / `errorContainer` / `brandContainer` fill).",
+        "The Thumbnail sits over a dark photo / pattern / video frame where the image's own edge tones can collide with the avatar's edge tones.",
+        "Two adjacent Thumbnails partially overlap (avatar stack, cluster) and need a clean separator between them."
+      ],
+      "whenToSkipIt": [
+        "Plain `surface*` row hosts (List / Feed / SuggestionList / NavigationBar leading) with no imagery underneath — `surface`-on-`surface` halo is invisible and costs render work for zero gain.",
+        "The host's own chrome already provides the separator (outlined card, hairline divider directly under the avatar).",
+        "Tiny rungs (`size={16}` / `size={20}`) where the halo would dominate the visible glyph."
+      ],
+      "canonicalHosts": [
+        "ProfileHeader avatar (always `outlined={true}` — half-overlaps cover band)",
+        "ProfileCarousel avatar (always `outlined={true}` — half-overlaps card cover image)"
+      ]
+    }
+  },
+  "slots": {
+    "image": {
+      "required": true,
+      "description": "Circular image asset (raster PNG / JPG / WebP or vector SVG). Fills the whole container at radius.full. Image-only — no text fallback. When no real asset is available, fill with the bundled placeholder `/placeholder.png` so the slot still resolves to an image.",
+      "accepts": [
+        "image"
+      ],
+      "assetType": "image",
+      "placeholder": "/placeholder.png"
+    },
+    "updateDot": {
+      "required": false,
+      "description": "Brand-tone dot at the top-right. aria-hidden — decorative. Rendered by the [Badge](../badge/badge.md) component's `dot-md` / `dot-sm` rungs so the dot, its halo, and its rung names stay in lockstep with the Badge family. Thumbnail picks `dot-md` (8×8) at the 32 / 40 / 48 / 56 rungs and `dot-sm` (4×4) at the 16 / 20 / 24 rungs.",
+      "intrinsic": true,
+      "rendersAs": "badge:dot-md|dot-sm"
+    },
+    "logoBadge": {
+      "required": false,
+      "description": "16×16 circular badge at the bottom-right, used to attach a sub-brand glyph.",
+      "accepts": [
+        "icon",
+        "image"
+      ]
+    }
+  },
+  "appearance": {
+    "containerRadius": "sys.radius.full",
+    "containerOutline": {
+      "appliesWhen": "props.outlined === true",
+      "color": "sys.color.surface",
+      "width": "sys.borderWidth.thin",
+      "rendering": "box-shadow (outset, 0 0 0 width color) so the halo never reflows the slot's intrinsic diameter — same no-layout-stroke contract every other Chorus surface follows. Pairs the halo with the host's `surface*` tier so the ring blends into the chrome around it while separating the Thumbnail from a contrasting backdrop (cover image, brand tonal strip, gradient band)."
+    },
+    "imageFallbackFill": "sys.color.surfaceContainerHigh",
+    "imageFallbackImage": "/placeholder.png",
+    "imageFallbackImageRendering": "background-image, cover, center — paints under the runtime <img>; visible only when the inline image is missing or fails to load, so the slot still resolves to an image rather than an empty surface tone.",
+    "imageFallbackGlyphColor": "sys.color.onSurfaceVariant",
+    "updateDotFill": "sys.color.brand",
+    "updateDotRadius": "sys.radius.full",
+    "updateDotHalo": {
+      "color": "sys.color.surface",
+      "width": "sys.borderWidth.hairline",
+      "rendering": "box-shadow"
+    },
+    "logoBadgeRadius": "sys.radius.full",
+    "logoBadgeHalo": {
+      "color": "sys.color.surface",
+      "width": "sys.borderWidth.hairline",
+      "rendering": "box-shadow"
+    }
+  },
+  "sizes": {
+    "16": {
+      "diameter": "ref.space.200",
+      "updateDot": "6 × 6",
+      "logoBadge": "16 × 16"
+    },
+    "20": {
+      "diameter": "ref.space.250",
+      "updateDot": "6 × 6",
+      "logoBadge": "16 × 16"
+    },
+    "24": {
+      "diameter": "ref.space.300",
+      "updateDot": "6 × 6",
+      "logoBadge": "16 × 16"
+    },
+    "32": {
+      "diameter": "ref.space.400",
+      "updateDot": "8 × 8",
+      "logoBadge": "16 × 16"
+    },
+    "40": {
+      "diameter": "ref.space.500",
+      "updateDot": "8 × 8",
+      "logoBadge": "16 × 16"
+    },
+    "48": {
+      "diameter": "ref.space.600",
+      "updateDot": "8 × 8",
+      "logoBadge": "16 × 16"
+    },
+    "56": {
+      "diameter": "ref.space.700",
+      "updateDot": "8 × 8",
+      "logoBadge": "16 × 16"
+    }
+  },
+  "states": {
+    "note": "Thumbnail is not an interactive primitive — no hover / pressed / focused / disabled of its own. When inside an interactive row, the row owns state and the focus ring paints around the row's bounds. Fallback form: when `src` is missing or the server fails to deliver the image, the slot paints the bundled `/placeholder.png` as a background-image over a `surfaceContainerHigh` base so the slot still resolves to an image rather than an empty surface."
+  },
+  "behavior": {
+    "slotOmissionCollapses": "Both badges (updateDot, logoBadge) drop out of the layout entirely when absent — no reserved corner whitespace.",
+    "badgesOverlay": "Both badges are absolutely positioned over the image; the container's overall footprint is the image's diameter regardless of whether the badges are present. The 1px surface halo is rendered as a box-shadow.",
+    "outlinedHalo": "When `outlined={true}`, the container paints a 2-token (`sys.borderWidth.thin`) `sys.color.surface` halo via `box-shadow` — outset of the diameter, never reflowing the slot. The corner badges' own 1-token halos are layered above it. Composes cleanly with `updateDot` and `logoBadge`.",
+    "imageClip": "Container's radius.full plus overflow: hidden clips the image to a perfect circle even when the source is rectangular.",
+    "noTextFallback": "Slot only renders <img> content — there is no text fallback. When `src` is omitted or the server fails to deliver the image, the slot's background paints the bundled `/placeholder.png` over a `surfaceContainerHigh` base. The placeholder is the image-area's runtime safety net for load failures; design-time scaffolds should pass the same URL through `src` explicitly so the contract is visible in the composition rather than hidden in the CSS layer.",
+    "updateDotBreakpoint": "Dot drops from 8×8 (at and above rung 32, including 56) to 4×4 (rungs 24 / 20 / 16) so it reads as highlight, not occluder, on the smaller diameters.",
+    "logoBadgeFixed": "Pinned at 16×16 at every rung — at the 16px Thumbnail the badge intentionally overlaps so the host image still reads through."
+  },
+  "forbidden": [
+    "thumbnail rendered as a raw <img> outside the chorus-thumbnail wrapper — the wrapper owns the placeholder fallback and the surface halo",
+    "border-radius override on a thumbnail — the radius comes from the variant (full for avatar, sys.radius.md for media) and is non-negotiable",
+    "size override outside the declared rung — 16 / 20 / 24 / 32 / 40 / 48 / 56 are the canonical sizes",
+    "alt prop omitted or set to a generic 'thumbnail' string — alt names the subject of the image, not the slot role",
+    "Thumbnail half-overlapping a cover image (ProfileHeader, ProfileCarousel, any Hero) WITHOUT `outlined={true}` — the avatar's edge tones can collide with the image's edge tones, costing the circle its perceived boundary. Forward `outlined` to the Thumbnail; don't paint a halo on the host's wrapper",
+    "hand-rolled `border:` or `outline:` on the Thumbnail container to fake the halo — reflows the slot's diameter and breaks the rung's intrinsic geometry. Use the `outlined` prop, which paints via outset `box-shadow`"
+  ]
+}