@teamblind-chorus/ui 1.0.0

package/agents/components/side-sheet/side-sheet.md

@@ -0,0 +1,154 @@
+# SideSheet
+
+Off-canvas content column anchored to the leading or trailing edge of the viewport. Pairs with [BottomSheet](../bottom-sheet/bottom-sheet.md) as the Sheet family's other anchor — BottomSheet for committed-sheet flows, SideSheet for off-canvas navigation columns, settings panes, channel directories, filter rails.
+
+**Reach for this when** an off-canvas column belongs next to the current page — a navigation drawer, a channel / topic / saved-item directory, a filter rail, a settings pane. **Skip when** the surface is a committed-sheet flow (use [BottomSheet](../bottom-sheet/bottom-sheet.md)), a confirmation prompt (use [Dialog](../dialog/dialog.md)), a labelled in-flow block (use [Section](../section/section.md)), or a permanent app-shell navigation (use [TabBar](../tab-bar/tab-bar.md) / [NavigationBar](../navigation-bar/navigation-bar.md)).
+
+**Layout inset.** `bounded-surface` — a portal-rendered off-canvas card (same family as `BottomSheet` / `Dialog`), mounted into a `document.body` portal. Its body is **full-bleed**: it pays no inline gutter, so each child owns its own `container.md` (16) rail and aligns at 16 with row backgrounds bleeding the full column. Full-bleed children (List, Feed) need **no** negative-margin opt-out here — that idiom is only for the inline-gutter surfaces (Dialog / BottomSheet); a bounded child needing an inset supplies its own inline margin. See [AGENTS.md § Composition rules](../../../AGENTS.md#composition-rules).
+
+Composition is free-form via `children` — canonical fill is a [Header](../header/header.md) (`size="medium"`) heading + an embedded [list/entry](../list/entry.md) directory stack (40 avatar + label + inline count Badge + optional trailing icon toggle), optionally followed by another Header + List(entry) pair and a pinned footer commit.
+
+## Default
+
+A left-anchored navigation drawer composed of three Header (medium) + List(entry) directory pairs and a pinned footer commit. The canonical "channels directory" off-canvas pattern.
+
+```preview
+side-sheet/default
+---
+import { Badge, Button, Header, List, SideSheet, SideSheetGroup } from '@teamblind-chorus/ui';
+import { StarFillIcon } from '@teamblind-chorus/ui/icons';
+
+<SideSheet
+  inline
+  open
+  onClose={() => {}}
+  aria-label="Channels drawer"
+  footer={
+    <Button variant="text" size="small" appearance="accent" onClick={() => {}}>
+      Browse all channels
+    </Button>
+  }
+>
+  <SideSheetGroup>
+    <Header
+      size="medium"
+      label="My channels"
+      headerAction={{ label: '+ Create', onClick: () => {} }}
+    />
+    <List
+      variant="entry"
+      embedded
+      items={[
+        { value: 'team-blind',     label: 'Team Blind',         thumbnail: { alt: 'Team Blind' } },
+        { value: 'startup-lounge', label: 'Startup Lounge',     count: <Badge size="small" count={64} />, thumbnail: { alt: 'Startup Lounge' } },
+        { value: 'it-pm',          label: 'IT PM · Management', count: <Badge size="small" count={12} />, thumbnail: { alt: 'IT PM · Management' } },
+      ]}
+    />
+  </SideSheetGroup>
+
+  <SideSheetGroup>
+    <Header size="medium" label="Favorites" />
+    <List
+      variant="entry"
+      embedded
+      items={[
+        {
+          value: 'sourdough',
+          label: 'Sourdough Bakers',
+          count: <Badge size="small" count={12} />,
+          thumbnail: { alt: 'Sourdough Bakers' },
+          trailingIcon: <Button variant="icon" size="medium" aria-label="Favorited" aria-pressed="true" icon={<StarFillIcon />} style={{ color: 'var(--sys-color-icon-yellow)' }} onClick={() => {}} />,
+        },
+        {
+          value: 'stocks',
+          label: 'Stocks & Investing',
+          count: <Badge size="small" count={142} />,
+          thumbnail: { alt: 'Stocks & Investing' },
+          trailingIcon: <Button variant="icon" size="medium" aria-label="Favorited" aria-pressed="true" icon={<StarFillIcon />} style={{ color: 'var(--sys-color-icon-yellow)' }} onClick={() => {}} />,
+        },
+        {
+          value: 'movie-talk',
+          label: 'Movie Talk',
+          count: <Badge size="small" count={24} />,
+          thumbnail: { alt: 'Movie Talk' },
+          trailingIcon: <Button variant="icon" size="medium" aria-label="Favorited" aria-pressed="true" icon={<StarFillIcon />} style={{ color: 'var(--sys-color-icon-yellow)' }} onClick={() => {}} />,
+        },
+      ]}
+    />
+  </SideSheetGroup>
+
+  <SideSheetGroup>
+    <Header size="medium" label="Following" />
+    <List
+      variant="entry"
+      embedded
+      items={[
+        {
+          value: 'career',
+          label: 'Career & Jobs',
+          count: <Badge size="small" count={24} />,
+          thumbnail: { alt: 'Career & Jobs' },
+          trailingIcon: <Button variant="icon" size="medium" aria-label="Favorite" aria-pressed="false" icon={<StarFillIcon />} style={{ color: 'var(--sys-color-icon-muted)' }} onClick={() => {}} />,
+        },
+        {
+          value: 'marketplace',
+          label: 'Marketplace',
+          count: <Badge size="small" count={12} />,
+          thumbnail: { alt: 'Marketplace' },
+          trailingIcon: <Button variant="icon" size="medium" aria-label="Favorite" aria-pressed="false" icon={<StarFillIcon />} style={{ color: 'var(--sys-color-icon-muted)' }} onClick={() => {}} />,
+        },
+        {
+          value: 'fashion',
+          label: 'Fashion & Beauty',
+          thumbnail: { alt: 'Fashion & Beauty' },
+          trailingIcon: <Button variant="icon" size="medium" aria-label="Favorite" aria-pressed="false" icon={<StarFillIcon />} style={{ color: 'var(--sys-color-icon-muted)' }} onClick={() => {}} />,
+        },
+      ]}
+    />
+  </SideSheetGroup>
+</SideSheet>
+```
+
+## Use cases
+
+### Single section
+
+One `SideSheetGroup` with a Header + List(entry) directory. Use for filter rails, settings groups, sub-navigation overlays.
+
+### With pinned commit
+
+Set the `footer` prop with a Text Button to pin a primary commit at the bottom (e.g. "Browse all channels", "Apply filters"). Footer stays flush while the body scrolls.
+
+## Slots
+
+- **scrim** — backdrop. Translucent black (`ref.palette.black.600`); dismisses on tap.
+- **card** — off-canvas column. Fixed width, full viewport height, flush against the `anchor` edge. `sys.color.surface` fill + `sys.elevation.sheet` shadow.
+- **body** — vertical scroll surface inside the card. **Full-bleed** — no inline gutter; each child pays its own `container.md` (16) rail. Block padding is `0` at the top (each group's leading Header supplies the 24 top inset itself) and `24px` at the bottom; the body adds no inter-child gap — the Header-driven block rhythm is the single source of truth.
+- **group** *(SideSheetGroup)* — bundle of one Header + a directory primitive (canonical: an embedded [list/entry](../list/entry.md) stack) inside the body. The full-bleed Header drives the rhythm: its `24px` (`layout.stack.lg`) block-start is both the gap **between groups** and the body's top inset for the first group; its `16px` (`layout.stack.md`) block-end is the header↔directory gap. The group adds no sibling margin of its own. Because the body is full-bleed, the `<List variant="entry">` aligns at the same 16 rail as the Header with no opt-out.
+- **footer** *(optional)* — pinned bottom action rail. Single Text Button or compact action node; separated by an `outlineVariant` hairline.
+
+## Trailing favorite-star contract
+
+When a channel / directory row carries a favorite toggle on its trailing edge, use a single fill-only glyph (`StarFillIcon`) whose **colour** communicates the pressed state — never swap between outline (`StarIcon`) and fill (`StarFillIcon`) for the same affordance:
+
+| State    | Icon            | Colour                          | aria-pressed |
+|----------|-----------------|---------------------------------|--------------|
+| Active   | `StarFillIcon`  | `var(--sys-color-icon-yellow)`  | `true`       |
+| Inactive | `StarFillIcon`  | `var(--sys-color-icon-muted)`   | `false`      |
+
+The shape stays constant so the trailing edge has a stable hit-target footprint; only the colour token flips. This is the canonical pattern across Side Sheet, channel lists, directory rows.
+
+## Behavior
+
+- **Portal** — renders into a `document.body` portal when `open` (SSR-safe; target resolves on mount). `inline` mode bypasses the portal for docs previews.
+- **Scroll lock** — body scroll is locked while open.
+- **Focus** — on open, focus moves to the first focusable inside the card. On close, focus returns to the trigger.
+- **Dismiss** — backdrop tap and Escape key both invoke `onClose`. The component never closes itself; consumers own the open state.
+- **Full-bleed body** — the body pays no inline padding, so full-bleed children (List, Feed) rendered directly inside it pay their own `container.md` (16) rail and align at 16 with the Header, row backgrounds bleeding the full column — no negative-margin opt-out needed (unlike the inline-gutter Dialog / BottomSheet). A *bounded* child that needs an inset (a tinted Banner block) supplies its own inline margin since the body won't inset it.
+
+## Forbidden
+
+- `open` without `onClose` — the sheet must own a dismiss path.
+- Fixed positioning inside children — the body owns the scroll surface.
+- Multiple SideSheets open at once — nest a BottomSheet inside if a sub-step is needed.
+- `anchor="top"` / `anchor="bottom"` — top is out of scope; bottom belongs to BottomSheet.

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

@@ -0,0 +1,109 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "SideSheet",
+  "family": "side-sheet",
+  "subcomponent": "side-sheet",
+  "exportAlias": "SideDrawer",
+  "description": "Off-canvas content column. Renders into a body portal when open, locks body scroll, returns focus to the trigger on close, dismisses on Escape / backdrop tap. The card is a fixed-width column flush against the leading or trailing edge of the viewport; the body owns its own surface padding so consumers compose primitives directly inside without paying padding twice. Lists inside the body negate the inline padding so row leading edges land flush.",
+  "element": "aside",
+  "props": {
+    "open": {
+      "type": "boolean",
+      "required": true,
+      "description": "Controlled open state."
+    },
+    "onClose": {
+      "type": "function",
+      "required": true,
+      "description": "Fired on backdrop tap, Escape key, or any consumer-triggered close."
+    },
+    "anchor": {
+      "type": "literal",
+      "values": ["left", "right"],
+      "default": "left",
+      "description": "Edge the card sits flush against. `left` (default) — the off-canvas navigation / channel directory pattern. `right` — filter rail, settings pane, or sub-nav overlay on right-handed surfaces."
+    },
+    "width": {
+      "type": "number | string",
+      "default": 320,
+      "description": "Card width. Number → pixels; string → any CSS length (`'80vw'`, `'min(320px, 80vw)'`). Mobile-first: defaults to 320 so the trailing 40-ish px peek lets the user see the page underneath at a glance."
+    },
+    "footer": {
+      "type": "node",
+      "optional": true,
+      "description": "Pinned bottom action rail. Hosts a single Text Button or any compact action node (e.g. \"Browse all channels\"). Stays flush at the card bottom while the body scrolls."
+    },
+    "children": {
+      "type": "node",
+      "required": true,
+      "description": "Body content. Free-form composition; the canonical fill is one or more Header (size=\"medium\") + embedded [list/entry](../list/entry.md) directory stack pairs (40 avatar + label + inline count Badge + optional trailing icon toggle)."
+    },
+    "inline": {
+      "type": "boolean",
+      "default": false,
+      "description": "Docs-only — renders the sheet inline (no portal, no fixed positioning, no body scroll lock) so the card can be shown next to other primitives in a documentation preview without occluding the page. Never use in production."
+    }
+  },
+  "slots": {
+    "scrim": {
+      "required": true,
+      "description": "Backdrop. Translucent black overlay (`ref.palette.black.600`) that absorbs all clicks outside the card and dismisses the sheet on tap."
+    },
+    "card": {
+      "required": true,
+      "description": "Off-canvas column. Fixed width, full viewport height, flush against the `anchor` edge. `surface` fill + `elevation.sheet` shadow."
+    },
+    "body": {
+      "required": true,
+      "description": "Vertical scroll surface inside the card. Pays its own gutter (16px inline / 24px block via `layout.container.md` / `layout.container.lg`) and stacks children at 24px (`layout.stack.lg`) — the rhythm BETWEEN groups."
+    },
+    "group": {
+      "required": false,
+      "description": "Header + List bundle (the `SideSheetGroup` primitive). Internal gap 16px (`layout.stack.md`) so the heading reads attached to its items; body-level 24px rhythm then separates one group from the next. Wrap each (Header + List) pair in a group so the visual grouping reads consistently across the drawer column."
+    },
+    "footer": {
+      "required": false,
+      "description": "Pinned bottom action rail. Separated from the body by a `outlineVariant` hairline. `16px` inline + block padding."
+    }
+  },
+  "sizing": {
+    "scrimColor": "ref.palette.black.600",
+    "cardBg": "sys.color.surface",
+    "cardElevation": "sys.elevation.sheet",
+    "cardDefaultWidth": "320px",
+    "bodyPadding": "sys.layout.container.lg (24) block × sys.layout.container.md (16) inline",
+    "bodyStackGap": "sys.layout.stack.lg (24) — between groups",
+    "groupStackGap": "sys.layout.stack.md (16) — within group, Header → List",
+    "footerPadding": "sys.layout.container.md (16)",
+    "footerDivider": "sys.borderWidth.hairline / sys.color.outlineVariant"
+  },
+  "states": {
+    "open": {
+      "description": "Card rendered into a body portal; body scroll locked; focus moves to the first focusable inside the card."
+    },
+    "closed": {
+      "description": "Component returns null; focus returns to the last-focused element before open."
+    }
+  },
+  "behavior": {
+    "portal": "Renders into a `document.body` portal when `open` and not `inline`. SSR-safe: the portal target resolves on mount.",
+    "scrollLock": "Body scroll is locked while open (and not inline).",
+    "focus": "On open, focus moves to the first focusable inside the card and is trapped there (see accessibility.focusTrap). On close, focus returns to the trigger.",
+    "dismiss": "Backdrop tap and Escape key both invoke `onClose`. The component never closes itself — consumers own the open state.",
+    "fullBleedListInside": "Lists rendered as direct children of the body negate the body's 16px inline padding (margin-inline negative + width opt-out) so row leading edges land flush with the body's leading inset, same precedent as BottomSheet → overflow / nested-step."
+  },
+  "accessibility": {
+    "role": "the scrim-backed sheet is a blocking modal, so the `aside` element carries role='dialog' (which overrides `aside`'s default complementary-landmark semantics) plus aria-modal='true'. The bare `aside` semantics alone are wrong for a surface that inerts the page behind a scrim. (If a non-scrim, docked/standard variant is later added, that variant keeps the plain `aside` complementary landmark and omits aria-modal — see the standard-side-sheet coverage note.)",
+    "ariaModal": "aria-modal='true' on the card — content behind the scrim is inert to assistive tech, mirroring the scrim's pointer-event block.",
+    "labelling": "aria-labelledby points at the heading composed at the top of the body when present; otherwise the consumer MUST supply an aria-label so the modal is never announced unnamed.",
+    "focusTrap": "While open, Tab / Shift+Tab cycle only through the card's focusable descendants and wrap at the ends — focus never reaches the inert page behind the scrim. Required by the APG dialog-modal pattern; pairs with the existing focus-restore-to-trigger on close.",
+    "escape": "Esc invokes onClose (see behavior.dismiss)."
+  },
+  "forbidden": [
+    "open without onClose — the sheet must own a dismiss path",
+    "fixed positioning inside children — the body owns the scroll surface, children must not break out of it",
+    "non-Sheet-family chrome to imitate this shape (raw `<aside>` + Tailwind, custom drawer libraries) — reach for SideSheet",
+    "multiple SideSheets open at once — sheets are one-at-a-time; nest BottomSheet inside if a sub-step is needed",
+    "anchor=\"top\" / anchor=\"bottom\" — top is out of scope (no mobile pattern needs it), bottom belongs to BottomSheet"
+  ]
+}

package/agents/components/skeleton/skeleton.family.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "skeleton",
+  "name": "Skeleton",
+  "description": "Loading placeholder — a tonal block on `surfaceContainerHighest` with a slow opacity pulse that previews the footprint of content still being fetched. Three shapes share one anatomy and diverge only on the default footprint and corner radius: `text` (16px-line block, full-width default), `block` (rectangular fill — image, card body), `circle` (avatar-sized round). Compose multiple Skeletons inside `SkeletonGroup` to mirror the rhythm of a list row, feed post, or card. Single-spec family.",
+  "useCases": [
+    "list row loading state",
+    "feed post loading state",
+    "card / image-area placeholder",
+    "avatar placeholder",
+    "deferred-fetch chrome before the data resolves"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "inline",
+  "spec": "skeleton.md",
+  "usage": {
+    "note": "shape defaults to text; width/height are consumer-supplied. Stack multiples in SkeletonGroup to mirror the loading content's rhythm.",
+    "example": "<Skeleton shape=\"block\" height={120} />"
+  },
+  "subcomponents": [
+    {
+      "slug": "skeleton",
+      "spec": "skeleton.spec.json",
+      "md": "skeleton.md",
+      "default": true
+    }
+  ]
+}

package/agents/components/skeleton/skeleton.md

@@ -0,0 +1,123 @@
+# Skeleton
+
+A tonal placeholder block that previews where real content will render. Paints with a translucent `scrimSubtle` overlay (~8% black in light mode, ~8% white in dark) and a slow opacity pulse — visible on every host surface tier without colliding with a fixed neutral step. Three shapes — `text` (default 16-line block), `block` (image / card body), `circle` (avatar). Compose multiple Skeletons inside `SkeletonGroup` to mirror the loading content's rhythm.
+
+**Reach for this when** a list row, feed post, card cover, or avatar is being fetched and the host would otherwise paint empty. **Skip when** the wait is sub-300ms, the data is unavailable rather than loading (use an empty-state illustration), or the loading scope is the whole screen (use a centered progress indicator at page level).
+
+**Layout inset.** `inline` — Skeleton ships no padding or container chrome of its own. Sits as a leaf inside whichever surface it stands in for. Width and height are consumer-supplied. `SkeletonGroup` adds an 8px gap between stacked siblings.
+
+## Default
+
+A single text-line placeholder. 16px high, full-width by default.
+
+```preview
+skeleton/default
+---
+import { Skeleton } from '@teamblind-chorus/ui';
+
+<Skeleton />
+```
+
+## Use cases
+
+### Block
+
+A rectangular tonal block. 80px high by default — reads as a card cover, image area, or card body placeholder. Pass `height` to match the real content's footprint.
+
+```preview
+skeleton/block
+---
+import { Skeleton } from '@teamblind-chorus/ui';
+
+<Skeleton shape="block" height={120} />
+```
+
+### Circle
+
+An avatar placeholder. 40 × 40 by default — matches a 40-rung [Thumbnail](../thumbnail/thumbnail.md). Override `width` / `height` for a different rung.
+
+```preview
+skeleton/circle
+---
+import { Skeleton } from '@teamblind-chorus/ui';
+
+<Skeleton shape="circle" />
+```
+
+### List row
+
+A list-row loading state — leading 40-circle next to two stacked text lines. Use the same widths as the real row so the swap to live data doesn't reflow.
+
+```preview
+skeleton/list-row
+---
+import { Skeleton, SkeletonGroup } from '@teamblind-chorus/ui';
+
+<div style={{ display: 'flex', alignItems: 'center', gap: 'var(--sys-layout-inline-md)', padding: 'var(--sys-layout-container-xs) var(--sys-layout-container-md)' }}>
+  <Skeleton shape="circle" />
+  <SkeletonGroup aria-label="Loading row" style={{ flex: 1 }}>
+    <Skeleton width="60%" />
+    <Skeleton width="40%" />
+  </SkeletonGroup>
+</div>
+```
+
+### Feed post
+
+A feed-post loading state — author row (avatar + name + meta), title, two body lines, and a 16:9 cover block. Mirrors the rhythm of a real feed/post.
+
+```preview
+skeleton/feed-post
+---
+import { Skeleton, SkeletonGroup } from '@teamblind-chorus/ui';
+
+<SkeletonGroup aria-label="Loading post" style={{ padding: 'var(--sys-layout-container-md)' }}>
+  <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--sys-layout-inline-md)' }}>
+    <Skeleton shape="circle" width={32} height={32} />
+    <SkeletonGroup style={{ flex: 1 }}>
+      <Skeleton width="40%" />
+      <Skeleton width="25%" />
+    </SkeletonGroup>
+  </div>
+  <Skeleton width="85%" />
+  <Skeleton />
+  <Skeleton width="70%" />
+  <Skeleton shape="block" height={180} />
+</SkeletonGroup>
+```
+
+## Slots
+
+- **container** — the tonal block. `sys.color.scrimSubtle` fill (translucent inverse-tone overlay — black in light, white in dark), shape-dependent radius. Carries the pulse animation. `role='status'` + `aria-live='polite'` so screen readers announce the loading state without yanking focus.
+
+## Anatomy
+
+| Slot       | Token bindings |
+|------------|----------------|
+| container  | `sys.color.scrimSubtle` fill, `sys.radius.xs` corners (`text` / `block`) or `sys.radius.full` (`circle`), no stroke |
+| text       | Default `ref.space.200` (16px) height × 100% width |
+| block      | Default `ref.space.1000` (80px) height × 100% width |
+| circle     | Default `ref.space.500` × `ref.space.500` (40 × 40) round |
+| group gap  | `SkeletonGroup` flex column, `sys.layout.stack.xs` (8px) between stacked Skeletons |
+
+## Shapes
+
+| Shape    | Default footprint | Corners            | When to reach                                                            |
+|----------|-------------------|--------------------|-------------------------------------------------------------------------|
+| `text`   | `ref.space.200` × 100%       | `sys.radius.xs`    | Single line of body copy — the canonical default.                       |
+| `block`  | `ref.space.1000` × 100%      | `sys.radius.xs`    | Image area, card cover, multi-line body block. Override `height` to fit. |
+| `circle` | `ref.space.500` × `ref.space.500` | `sys.radius.full` | Avatar placeholder — matches a 40-rung [Thumbnail](../thumbnail/thumbnail.md). |
+
+## States
+
+| State     | Animation                            | Notes |
+|-----------|--------------------------------------|-------|
+| `default` | `pulse 1.6s ease-in-out infinite`     | Opacity oscillates between `0.5` and `1`. No hue shift. |
+| reduced-motion | suppressed                       | Under `prefers-reduced-motion: reduce` the pulse halts and the block stays at full opacity. |
+
+## Behavior
+
+- **Footprint matches content.** Pass `width` / `height` so the placeholder matches the data it replaces — swap should not reflow.
+- **Group for multi-line.** Stack Skeletons inside a `SkeletonGroup` to keep the 8px sibling gap consistent.
+- **Single screen role.** `role='status'` + `aria-live='polite'` announces loading without interrupting focus. Announcement carries the `aria-label` (defaults to `'Loading'`).
+- **Atomic swap.** Replace the Skeleton with real content in one render — no cross-fade.

package/agents/components/skeleton/skeleton.spec.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "Skeleton",
+  "family": "skeleton",
+  "description": "Single tonal placeholder block painted on `sys.color.scrimSubtle` (~8% inverse-tone overlay — black scrim in light mode, white scrim in dark) with a slow opacity pulse (`0.5 → 1 → 0.5` over 1.6s). The translucent fill stays visible on every host surface tier, so the placeholder reads cleanly whether it sits on a plain page surface, an elevated container, a hero band, or a coloured card. Three shapes select the default footprint and corner radius: `text` (`ref.space.200` / 16px high, full-width — single line of body copy), `block` (`ref.space.1000` / 80px high, full-width — image / card body) and `circle` (`ref.space.500` × `ref.space.500` / 40 × 40, fully rounded — avatar). Consumer-supplied `width` / `height` props override the default footprint. Compose multiple Skeletons inside `SkeletonGroup` to mirror the rhythm of the content being loaded.",
+  "element": "span",
+  "props": {
+    "shape": {
+      "type": "enum",
+      "values": ["text", "block", "circle"],
+      "default": "text",
+      "description": "Selects the default footprint and corner radius. `text` and `block` paint at `sys.radius.xs`; `circle` paints at `sys.radius.full`."
+    },
+    "width": {
+      "type": "union",
+      "members": ["number", "string"],
+      "optional": true,
+      "description": "Overrides the default inline footprint. Numbers are coerced to `px`; strings pass through (`100%`, `'12rem'`, …). When omitted, `text` and `block` stretch to 100% of the host; `circle` keeps a `ref.space.500` (40 × 40) footprint."
+    },
+    "height": {
+      "type": "union",
+      "members": ["number", "string"],
+      "optional": true,
+      "description": "Overrides the default block footprint. Numbers are coerced to `px`. When omitted, `text` is `ref.space.200` (16px), `block` is `ref.space.1000` (80px), `circle` is `ref.space.500` (40px)."
+    },
+    "aria-label": {
+      "type": "string",
+      "optional": true,
+      "description": "Accessible label announced by screen readers. Defaults to `'Loading'`."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Tonal block. `sys.color.scrimSubtle` fill (translucent black/white inverse-tone overlay — visible on every host surface), shape-dependent radius, no stroke. Carries the pulse animation. `role='status'` + `aria-live='polite'` so screen readers announce the loading state without yanking focus.",
+      "intrinsic": true
+    }
+  },
+  "sizing": {
+    "background": "sys.color.scrimSubtle",
+    "radiusText": "sys.radius.xs",
+    "radiusBlock": "sys.radius.xs",
+    "radiusCircle": "sys.radius.full",
+    "defaultTextHeight": "ref.space.200",
+    "defaultBlockHeight": "ref.space.1000",
+    "defaultCircleSize": "ref.space.500",
+    "groupGap": "sys.layout.stack.xs"
+  },
+  "appearances": {
+    "default": {
+      "background": "sys.color.scrimSubtle",
+      "note": "The only fill tone — Skeleton has no emphasis axis. Painted as a translucent ~8% inverse-tone overlay (black in light mode, white in dark) so the placeholder stays visible on every host surface tier (surface, surfaceContainer, surfaceContainerHigh, hero, …) without colliding with a fixed neutral step. The pulse modulates opacity, not hue, so the placeholder reads as anonymous chrome."
+    }
+  },
+  "states": {
+    "default": {
+      "animation": "chorus-skeleton-pulse 1.6s ease-in-out infinite",
+      "note": "Opacity oscillates between 0.5 and 1 over 1.6s. The 0.5 floor is a family constant — no semantic token rung is allocated for the opacity-pulse minimum since it is unique to Skeleton. The animation respects `prefers-reduced-motion: reduce` — pulse halts and the block stays at full opacity."
+    }
+  },
+  "behavior": {
+    "ariaLive": "Container carries `role='status'` and `aria-live='polite'` so screen readers announce the loading state without interrupting the user's current focus. The visible block is decorative — the announcement comes from `aria-label` (defaults to `'Loading'`).",
+    "reducedMotion": "Under `@media (prefers-reduced-motion: reduce)` the pulse animation is suppressed entirely; the block stays at full opacity.",
+    "footprintOverrides": "`width` / `height` props win over the shape's default footprint, including for `circle` (a circle Skeleton at `width=60 height=60` stays a 60-rung round)."
+  },
+  "forbidden": [
+    "skeleton fill stepped to `sys.color.primary` or any chromatic tone — the placeholder must read as anonymous chrome, not as a content tone",
+    "shimmer / gradient sweep animation — Chorus skeletons modulate opacity only (one motion axis keeps the tier readable under reduced-motion fallback)",
+    "skeleton stacked vertically without a SkeletonGroup wrapper — group via SkeletonGroup so the 8px gap stays consistent across compositions",
+    "skeleton kept on-screen after the real content resolves — the placeholder must swap out atomically, not cross-fade with the loaded data",
+    "skeleton used as a permanent low-priority placeholder (empty-state / no-data illustration) — that role is an inline illustration + body copy, not a pulsing placeholder"
+  ]
+}

package/agents/components/status-tag/status-tag.family.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "status-tag",
+  "name": "StatusTag",
+  "description": "Small inline status pill — a tonal label-style mark sized for the trailing edge of a row label (10px text, 4px inline / 2px block padding, `sys.radius.xs` corners). Two appearances on a single emphasis axis: `neutral` (quiet `surfaceContainerHighest` + `onSurfaceVariant` — the informational default: pending, draft, queued) and `error` (`errorContainer` + `onErrorContainer` — the rejection / blocked state). Decorative — never an interactive surface. Distinct from [chip/tag](../chip/tag.md): Chip is a 32px-rung selectable / dismissable pill that lives in chip rows; StatusTag is a 16px-rung non-interactive mark that sits inline next to a row label. Single-spec family.",
+  "useCases": [
+    "row-label status annotation (pending / approved / rejected)",
+    "trailing inline status mark on a list / settings row",
+    "inline state pill in a feed-post header"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "inline",
+  "spec": "status-tag.md",
+  "usage": {
+    "note": "Decorative — never interactive. Takes label text as children; not a Chip and not a button.",
+    "example": "<StatusTag appearance=\"error\">Rejected</StatusTag>"
+  },
+  "subcomponents": [
+    {
+      "slug": "status-tag",
+      "spec": "status-tag.spec.json",
+      "md": "status-tag.md",
+      "default": true
+    }
+  ]
+}

package/agents/components/status-tag/status-tag.md

@@ -0,0 +1,114 @@
+# Status tag
+
+A small inline status pill — a tonal mark sized for the trailing edge of a row label. Two **appearances**: `neutral` (quiet informational default) and `error` (rejection / blocked). Decorative — never interactive.
+
+**Reach for this when** a row label needs a short state annotation inline — "pending" next to a user channel, "rejected" next to a failed approval, "draft" next to an in-progress post. **Skip when** the state is the row's primary content (use [List/standard](../list/standard.md) with `supportingText`), when the mark must be tappable (host row owns the click target), inside a chip row (use [chip/filter](../chip/filter.md) or [chip/tag](../chip/tag.md)), or when the mark names *who the person is* rather than a workflow state — 채널장 / 현직자 belong to [badge/role](../badge/role.md).
+
+**Layout inset.** `inline` — StatusTag ships no padding outside its pill chrome. Sits next to a host label with `sys.layout.container.2xs` (4px) inline gap supplied by the host column.
+
+## Default
+
+The `neutral` appearance — `sys.color.scrimSubtle` fill (the translucent inverse-tone scrim — ~8% black in light, ~8% white in dark) with `onSurfaceVariant` foreground. The quiet informational state.
+
+```preview
+status-tag/default
+---
+import { StatusTag } from '@teamblind-chorus/ui';
+
+<StatusTag>Pending</StatusTag>
+```
+
+## Use cases
+
+### Error
+
+The `error` appearance — `errorContainer` fill with an `onErrorContainer` foreground. The rejection / blocked / failed state.
+
+```preview
+status-tag/error
+---
+import { StatusTag } from '@teamblind-chorus/ui';
+
+<StatusTag appearance="error">Rejected</StatusTag>
+```
+
+### On a list row
+
+The canonical pairing — a `list/thumbnail` row whose label carries a trailing StatusTag with a `sys.layout.container.2xs` (4px) inline gap. The gap belongs to the label column; StatusTag carries no outer margin.
+
+```preview
+status-tag/list-row
+---
+import { List, StatusTag, Thumbnail } from '@teamblind-chorus/ui';
+
+<List
+  variant="standard"
+  items={[
+    {
+      value: 'ch-2',
+      label: (
+        <span style={{ display: 'inline-flex', alignItems: 'center', gap: 'var(--sys-layout-container-2xs)' }}>
+          User channel 2
+          <StatusTag>Pending</StatusTag>
+        </span>
+      ),
+      thumbnail: { alt: 'User channel 2', shape: 'circle' },
+    },
+    {
+      value: 'ch-3',
+      label: (
+        <span style={{ display: 'inline-flex', alignItems: 'center', gap: 'var(--sys-layout-container-2xs)' }}>
+          User channel 3
+          <StatusTag appearance="error">Rejected</StatusTag>
+        </span>
+      ),
+      thumbnail: { alt: 'User channel 3', shape: 'circle' },
+    },
+  ]}
+/>
+```
+
+### Inline in a paragraph
+
+A StatusTag tucked inline inside a paragraph or a feed-post header. Same 4px gap rule: the host column owns the whitespace, StatusTag stays a bare pill.
+
+```preview
+status-tag/inline
+---
+import { StatusTag } from '@teamblind-chorus/ui';
+
+<p style={{ font: '14px var(--sys-typo-fontFamily)', color: 'var(--sys-color-onSurface)' }}>
+  Shared document <StatusTag>Pending</StatusTag> is awaiting review.
+</p>
+```
+
+## Slots
+
+- **container** — tonal pill. 4px inline / 2px block padding, `sys.radius.xs` corners. Carries `role="status"` so the announcement reads as a state update.
+- **label** — tag text. 10px / Semibold / appearance-bound foreground. Short phrase (≤ 6 chars Latin, ≤ 4 CJK); `white-space: nowrap`.
+
+## Anatomy
+
+| Slot      | Token bindings |
+|-----------|----------------|
+| container | Fill + foreground per appearance, 4px inline / 2px block padding, `sys.radius.xs` corners |
+| label     | `ref.fontSize.125` (10px) / Semibold, 1.2 line-height |
+| gap from host label | `sys.layout.container.2xs` (4px) — paid by the host column, NOT by StatusTag |
+
+## Appearance
+
+| Appearance | Container fill                                                              | Foreground                       | When to reach                                                                  |
+|------------|-----------------------------------------------------------------------------|----------------------------------|-------------------------------------------------------------------------------|
+| `neutral`  | `sys.color.scrimSubtle` (translucent inverse-tone scrim — ~8% black light / ~8% white dark) | `sys.color.onSurfaceVariant`     | Quiet informational default — visible on every surface tier. In-progress / awaiting states — "pending", "draft", "queued", "in review". |
+| `error`    | `sys.color.errorContainer`                                                  | `sys.color.onErrorContainer`     | Rejection / blocked / failed state. Use sparingly. |
+
+## States
+
+StatusTag is decorative and carries **no** lifecycle states (no hover, pressed, focus, or disabled paint). If the state needs to be tappable, the host row is the interactive surface.
+
+## Behavior
+
+- **Decorative only.** Never a `<button>`, `<a href>`, or focusable element. The host row owns the click target.
+- **Inline next to a label.** The host label column carries a 4px gap to StatusTag; StatusTag itself has no outer margin.
+- **No wrap.** Container is `inline-block` with `white-space: nowrap`. If the phrase is long, the label is wrong — not the pill.
+- **Accessibility.** Container carries `role="status"` so screen readers announce the tag as a state update rather than as an unlabelled span.