@teamblind-chorus/ui 1.1.0 → 2.0.0

package/agents/components/chip/tag.spec.json

@@ -3,7 +3,7 @@
   "name": "Chip",
   "family": "chip",
   "subcomponent": "tag",
-  "description": "Informational chip. Square-cornered metadata label. Passive (or dismissable via trailing ×). No leading icon. Two appearances: `default` paints the translucent `sys.color.scrimSubtle` scrim (~8% inverse-tone overlay — black in light, white in dark) so the tag adopts whatever surface sits behind it; `accent` paints a tonal pale-primary container (`sys.color.primaryContainer`) with primary label for tags that need to pop against the surface.",
+  "description": "Informational chip. Square-cornered metadata label. Passive (or dismissable via trailing ×). No leading icon. Two appearances: `default` paints the translucent `sys.color.background.neutral` scrim (~8% inverse-tone overlay — black in light, white in dark) so the tag adopts whatever surface sits behind it; `accent` paints a tonal pale-primary container (`sys.color.background.selected`) with primary label for tags that need to pop against the surface.",
   "element": "span",
   "props": {
     "variant": {
@@ -44,15 +44,15 @@
   },
   "appearances": {
     "default": {
-      "background": "sys.color.scrimSubtle",
-      "label": "sys.color.onSurface",
+      "background": "sys.color.background.neutral",
+      "label": "sys.color.text.default",
       "border": null,
       "default": true,
-      "note": "Background is the translucent inverse-tone scrim (`sys.color.scrimSubtle` — black 8% in light mode, white 8% in dark) so the tag harmonises with whatever surface sits behind it — body, raised card, BottomSheet — instead of pinning to a fixed neutral step. Same Banner-style fill used by Progress track, StatusTag neutral, and Skeleton; sys-color is theme-aware so a single token resolves correctly in both modes."
+      "note": "Background is the translucent inverse-tone scrim (`sys.color.background.neutral` — black 8% in light mode, white 8% in dark) so the tag harmonises with whatever surface sits behind it — body, raised card, BottomSheet — instead of pinning to a fixed neutral step. Same Banner-style fill used by Progress track, StatusTag neutral, and Skeleton; sys-color is theme-aware so a single token resolves correctly in both modes."
     },
     "accent": {
-      "background": "sys.color.primaryContainer",
-      "label": "sys.color.primary",
+      "background": "sys.color.background.selected",
+      "label": "sys.color.text.link",
       "border": null,
       "note": "Tonal accent: pale primary container background with primary label. Sys-color tokens are theme-aware, so no separate dark binding is needed — the resolved tokens pick the right values per theme. Use for tags that should pop against the surface (e.g. Popular Tags in compose, highlighted hashtags) where the default overlay is too quiet."
     }
@@ -73,26 +73,49 @@
         "opacity": "sys.state.pressed"
       }
     },
+    "focused": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.focus"
+      },
+      "focusRing": {
+        "composition": "outward",
+        "layer": "::after overlay — position:absolute, inset:0, no reflow (DESIGN.md Focus ring composition)",
+        "innerCounterRing": {
+          "width": "sys.borderWidth.hairline",
+          "color": "sys.color.border.focused"
+        },
+        "outerRing": {
+          "width": "sys.borderWidth.thin",
+          "color": "sys.color.border.focused"
+        }
+      },
+      "note": "Keyboard-focus (:focus-visible) visual. Mirrors the `focusIndicator` block (the external-reader contract); kept here so spec-only renderers see focus in the states map. Composes over the lifecycle state the chip is in; never via plain mouse click."
+    },
     "disabled": {
       "overlay": null,
-      "containerOpacity": "sys.state.disabled",
+      "background": "sys.color.background.disabled",
+      "label": "sys.color.text.disabled",
+      "border": {
+        "width": "sys.borderWidth.hairline",
+        "color": "sys.color.border.bold"
+      },
       "suppressFocusRing": true,
-      "cursor": "not-allowed"
+      "cursor": "not-allowed",
+      "note": "Explicit disabled (no opacity): neutral disabled fill + bold border so the shape reads on any surface, plus disabled label. Overrides the rest/selected appearance."
     }
   },
   "focusIndicator": {
     "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. Composes over whichever lifecycle state the chip is in. Applies only when the chip is interactive (a dismiss trailingIcon is present). The `states.focused` block above is kept for JSX runtime consumers; this block is the parallel external-reader contract.",
     "composition": "outward",
-    "compositionReason": "Action affordance with breathing room around it; the 3px outward extent is reserved by the surrounding layout.",
+    "compositionReason": "Action affordance with breathing room around it; the 1px outward ring is reserved by the surrounding layout.",
     "overlay": {
       "color": "label",
       "opacity": "sys.state.focus"
     },
     "ring": {
-      "outerWidth": "sys.borderWidth.thin",
-      "outerColor": "sys.color.focus",
-      "insetWidth": "sys.borderWidth.hairline",
-      "insetColor": "sys.color.focusInset"
+      "width": "sys.borderWidth.hairline",
+      "color": "sys.color.border.focused"
     },
     "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
   },

package/agents/components/dialog/dialog.md

@@ -33,9 +33,7 @@ const [open, setOpen] = useState(false);
 </>
 ```
 
-## Use cases
-
-### With image
+## Image
 
 Pass an `image` to add a centred illustration between title and actions. With the image present, the whole stack centre-aligns. `imageFirst` (default `true`) controls whether the image sits under the title or the body.
 

package/agents/components/dialog/dialog.spec.json

@@ -90,18 +90,18 @@
   "sizing": {
     "scrimTint": "ref.palette.black.600",
     "scrimPaddingInline": "ref.space.500",
-    "containerFill": "sys.color.surfaceContainerHigh",
+    "containerFill": "sys.color.surface.default",
     "containerRadius": "sys.radius.xl",
     "elevation": "sys.elevation.overlay",
     "containerPadding": "sys.layout.container.lg",
     "maxWidth": "480px",
     "titleTypo": "sys.typo.heading.sm",
-    "titleColor": "sys.color.onSurface",
+    "titleColor": "sys.color.text.default",
     "imageWidth": "100%",
     "imageHeight": "auto",
     "imageRadius": "sys.radius.lg",
     "bodyTypo": "sys.typo.body.sm",
-    "bodyColor": "sys.color.onSurfaceVariant",
+    "bodyColor": "sys.color.text.subtle",
     "interSlotGap": "sys.layout.stack.md",
     "actionsStackGap": "sys.layout.stack.xs"
   },

package/agents/components/directory-list/directory-list.md

@@ -31,9 +31,7 @@ import { DirectoryList } from '@teamblind-chorus/ui';
 />
 ```
 
-## Use cases
-
-### With header action
+## Header action
 
 Extends the header with a trailing `accent` Text Button when the screen has a broader index page to route to.
 

package/agents/components/directory-list/directory-list.spec.json

@@ -55,12 +55,12 @@
     }
   },
   "sizing": {
-    "containerFill": "sys.color.surface",
+    "containerFill": "sys.color.surface.default",
     "containerPaddingBlock": "sys.layout.container.lg",
     "containerPaddingInline": "sys.layout.container.md",
     "headerToListGap": "sys.layout.stack.md",
     "labelTypo": "sys.typo.heading.md",
-    "labelColor": "sys.color.onSurface",
+    "labelColor": "sys.color.text.default",
     "headerActionRendersAs": "Button variant='text' size='xsmall' appearance='accent' — link-affordance accent rule.",
     "rowRung": "list/entry size=\"large\" — 48 avatar, inline.lg gap, label.md primary, label.sm secondary + description.",
     "rowInlinePaddingNote": "Each row keeps the list/entry native sys.layout.container.md inline padding (the tap target reaches the surface edge) and adds margin-inline: calc(-1 * sys.layout.container.md) so the visible avatar sits flush at the section's content rail — aligned with the header label at 16 from the surface.",

package/agents/components/divider/divider.family.json

@@ -2,7 +2,7 @@
   "$schema": "../../family.schema.json",
   "family": "divider",
   "name": "Divider",
-  "description": "Region separator — a heavy tonal band that splits adjacent regions whose vertical rhythm alone doesn't read as a boundary. Painted with `sys.color.scrimSubtle` (~8% inverse-tone overlay — black scrim in light mode, white scrim in dark) so the band stays visible on every host surface tier (`surface`, `surfaceContainer`, `surfaceContainerHigh`, hero, …) without colliding with a fixed neutral step. Same scrim used by Banner default, Chip / Tag default, Progress track, StatusTag neutral, and Skeleton — Divider is the section-level member of that family. Reserved for *region*-level separation between groups that don't share an enclosing container (a feed segment ending and a followed-channels list beginning, a recents block ending above a single anchored CTA). Not for row-level separators inside a List (the list's own `divider={true}` paints those as a hairline `outlineVariant` rule). Single-spec family.",
+  "description": "Region separator — a heavy tonal band that splits adjacent regions whose vertical rhythm alone doesn't read as a boundary. Painted with `sys.color.border.default` (~8% inverse-tone overlay — black scrim in light mode, white scrim in dark) so the band stays visible on every host surface tier (`surface`, `surfaceContainer`, `surfaceContainerHigh`, hero, …) without colliding with a fixed neutral step. Same scrim used by Banner default, Chip / Tag default, Progress track, StatusTag neutral, and Skeleton — Divider is the section-level member of that family. Reserved for *region*-level separation between groups that don't share an enclosing container (a feed segment ending and a followed-channels list beginning, a recents block ending above a single anchored CTA). Not for row-level separators inside a List (the list's own `divider={true}` paints those as a hairline `border.default` rule). Single-spec family.",
   "useCases": [
     "between page-level content groups",
     "between a feed segment and the section below",

package/agents/components/divider/divider.md

@@ -2,19 +2,19 @@
 
 > 🇰🇷 한국어: [`i18n/ko/schema/components/divider/divider.md`](../../../i18n/ko/schema/components/divider/divider.md)
 
-A section-break band — a single full-bleed block painted with `sys.color.scrimSubtle` (~8% inverse-tone overlay — black in light mode, white in dark) at a fixed block thickness of `sys.layout.stack.xs` (8). Reach for it when two adjacent regions don't share an enclosing container and vertical rhythm alone doesn't read as a boundary — a directory of suggested channels ending and a fresh recommendation list beginning, a feed segment ending and a followed-channels list resuming, a promo strip ending and content picking up below.
+A section-break band — a single full-bleed block painted with `sys.color.border.default` (~8% inverse-tone overlay — black in light mode, white in dark) at a fixed block thickness of `sys.layout.stack.xs` (8). Reach for it when two adjacent regions don't share an enclosing container and vertical rhythm alone doesn't read as a boundary — a directory of suggested channels ending and a fresh recommendation list beginning, a feed segment ending and a followed-channels list resuming, a promo strip ending and content picking up below.
 
-**Reach for this when** the boundary between two regions is ambiguous because they share the same surface and vertical rhythm — the visitor's eye should *land* on the break, not infer it. **Skip when** the regions already sit on different surfaces (one card, one canvas — the surface change is the break), when one region carries a heading that itself reads as the start of a new block, or when the separation is between *rows of the same list* (List's own `divider={true}` paints those as a hairline `outlineVariant` rule).
+**Reach for this when** the boundary between two regions is ambiguous because they share the same surface and vertical rhythm — the visitor's eye should *land* on the break, not infer it. **Skip when** the regions already sit on different surfaces (one card, one canvas — the surface change is the break), when one region carries a heading that itself reads as the start of a new block, or when the separation is between *rows of the same list* (List's own `divider={true}` paints those as a hairline `border.default` rule).
 
-**Surface-agnostic by design.** The fill is `sys.color.scrimSubtle` — a ~8% inverse-tone overlay (black in light mode, white in dark) — so the band reads as a tint *darker than the host surface* without pinning to a fixed neutral step. The same band visibly separates regions on `surface`, `surfaceContainerHigh`, a hero panel, or a coloured card without retoning per-host. Same scrim tier as Banner default, Chip / Tag default, Progress track, StatusTag neutral, and Skeleton.
+**Surface-agnostic by design.** The fill is `sys.color.border.default` — a ~8% inverse-tone overlay (black in light mode, white in dark) — so the band reads as a tint *darker than the host surface* without pinning to a fixed neutral step. The same band visibly separates regions on `surface`, `surfaceContainerHigh`, a hero panel, or a coloured card without retoning per-host. Same scrim tier as Banner default, Chip / Tag default, Progress track, StatusTag neutral, and Skeleton.
 
-**Layout inset.** `full-bleed` — Divider stretches edge-to-edge inside the page-shell content box. It ships **no** inline padding, **no** outer margin, **no** corner radius, **no** stroke; it just paints `scrimSubtle` across a `sys.layout.stack.xs` (8) block. Drop it as a direct child of the page-shell `<main>` (or any full-width host column) between two regions — do not wrap in a `padding-inline` div, `className="px-*"`, or `style={{ padding }}`; the band reading edge-to-edge IS what makes it a region boundary.
+**Layout inset.** `full-bleed` — Divider stretches edge-to-edge inside the page-shell content box. It ships **no** inline padding, **no** outer margin, **no** corner radius, **no** stroke; it just paints `border.default` across a `sys.layout.stack.xs` (8) block. Drop it as a direct child of the page-shell `<main>` (or any full-width host column) between two regions — do not wrap in a `padding-inline` div, `className="px-*"`, or `style={{ padding }}`; the band reading edge-to-edge IS what makes it a region boundary.
 
-**Safe zone — none.** The parent column pays no `gap`, `padding-block`, or `margin-block` around Divider. The 8 of `scrimSubtle` is the breathing. If two regions feel cramped after dropping Divider between them, the fix is to add internal padding to the regions themselves (`layout.container.*`), never to wrap Divider in a spacer or paint outer margin on it.
+**Safe zone — none.** The parent column pays no `gap`, `padding-block`, or `margin-block` around Divider. The 8 of `border.default` is the breathing. If two regions feel cramped after dropping Divider between them, the fix is to add internal padding to the regions themselves (`layout.container.*`), never to wrap Divider in a spacer or paint outer margin on it.
 
 ## Default
 
-The single canonical band. 8 high, full inline width, `scrimSubtle` fill.
+The single canonical band. 8 high, full inline width, `border.default` fill.
 
 ```preview
 divider/default
@@ -24,9 +24,7 @@ import { Divider } from '@teamblind-chorus/ui';
 <Divider />
 ```
 
-## Use cases
-
-### Between adjacent lists
+## Between adjacent lists
 
 The canonical placement — a region break between two full-bleed lists stacked on the same page. Above: a directory of new channels (DirectoryList, an inert directory). Below: a recommendation set keyed to the visitor (SuggestionList, the pager-flavoured sibling). Both lists own their internal divider hairlines for rows, but the *boundary between the two lists* is a region break — that is the role Divider plays.
 
@@ -56,13 +54,13 @@ import { Divider, DirectoryList, SuggestionList } from '@teamblind-chorus/ui';
 
 ## Slots
 
-- **container** — the tonal band. `sys.color.scrimSubtle` fill, `sys.layout.stack.xs` (8) block thickness, full inline width, no padding, no border, no corner radius. The native `<hr>` element with all browser defaults reset. `aria-hidden="true"` by default — the band is decorative.
+- **container** — the tonal band. `sys.color.border.default` fill, `sys.layout.stack.xs` (8) block thickness, full inline width, no padding, no border, no corner radius. The native `<hr>` element with all browser defaults reset. `aria-hidden="true"` by default — the band is decorative.
 
 ## Anatomy
 
 | Slot       | Token bindings |
 |------------|----------------|
-| container  | `sys.color.scrimSubtle` fill, `sys.layout.stack.xs` (8) block height, 100% inline width, `border: none`, `margin: 0`, `border-radius: 0` |
+| container  | `sys.color.border.default` fill, `sys.layout.stack.xs` (8) block height, 100% inline width, `border: none`, `margin: 0`, `border-radius: 0` |
 
 ## Appearance
 
@@ -70,11 +68,11 @@ Single appearance — Divider has no emphasis axis, no orientation axis, and no
 
 | Appearance | Fill                       | When to use                                                                 |
 |------------|----------------------------|-----------------------------------------------------------------------------|
-| `default`  | `sys.color.scrimSubtle`    | The only mode. Same scrim used by Banner default / Chip-Tag default / Progress track / StatusTag neutral / Skeleton — Divider is the section-level member of that family. |
+| `default`  | `sys.color.border.default`    | The only mode. Same scrim used by Banner default / Chip-Tag default / Progress track / StatusTag neutral / Skeleton — Divider is the section-level member of that family. |
 
 ## Behavior
 
 - **aria-hidden by default.** The band is decorative chrome; screen-reader users navigate by headings and landmarks, not visual breaks. Override `aria-hidden={false}` only when the divider genuinely marks a semantic section change (rare — prefer a heading).
-- **Fixed thickness.** Block thickness is `sys.layout.stack.xs` (8) and is not a prop. Heavier bands compete with content; thinner bands collapse to a hairline (use the host's own `outlineVariant` border for row-level breaks, not Divider).
+- **Fixed thickness.** Block thickness is `sys.layout.stack.xs` (8) and is not a prop. Heavier bands compete with content; thinner bands collapse to a hairline (use the host's own `border.default` border for row-level breaks, not Divider).
 - **Full-bleed by contract.** The band must touch the page edge to read as a region boundary. Wrapping Divider in a padding-inline container breaks the affordance — see the AGENTS.md "one gutter, paid once" rule.
-- **Not a row separator.** Inside a List, rows already separate via the list's own `divider={true}` hairline `outlineVariant` rule. Reach for Divider only at the *region* level, between groups that don't share an enclosing container.
+- **Not a row separator.** Inside a List, rows already separate via the list's own `divider={true}` hairline `border.default` rule. Reach for Divider only at the *region* level, between groups that don't share an enclosing container.

package/agents/components/divider/divider.spec.json

@@ -2,7 +2,7 @@
   "$schema": "../../spec.schema.json",
   "name": "Divider",
   "family": "divider",
-  "description": "Section-break band — a single full-bleed block painted with `sys.color.scrimSubtle` (~8% inverse-tone overlay — black scrim in light mode, white scrim in dark) at a fixed block thickness of `sys.layout.stack.xs` (8). The translucent fill stays visible on every host surface tier, so the band reads as a region boundary whether it sits on plain page surface, an elevated container, a hero band, or a coloured card — without retoning per-host. No appearance axis, no thickness prop, no orientation prop: Divider ships one canonical band. The host paints no margin / padding / gap around it — the 8 of scrimSubtle IS the breathing.",
+  "description": "Section-break band — a single full-bleed block painted with `sys.color.border.default` (~8% inverse-tone overlay — black scrim in light mode, white scrim in dark) at a fixed block thickness of `sys.layout.stack.xs` (8). The translucent fill stays visible on every host surface tier, so the band reads as a region boundary whether it sits on plain page surface, an elevated container, a hero band, or a coloured card — without retoning per-host. No appearance axis, no thickness prop, no orientation prop: Divider ships one canonical band. The host paints no margin / padding / gap around it — the 8 of border.default IS the breathing.",
   "element": "hr",
   "props": {
     "aria-hidden": {
@@ -19,12 +19,12 @@
   "slots": {
     "container": {
       "required": true,
-      "description": "The tonal band itself. `sys.color.scrimSubtle` fill, `sys.layout.stack.xs` (8) block thickness, full inline width, no inline padding, no corner radius, no border. The native `<hr>` element with all browser defaults reset (no margin, no border, no background-image).",
+      "description": "The tonal band itself. `sys.color.border.default` fill, `sys.layout.stack.xs` (8) block thickness, full inline width, no inline padding, no corner radius, no border. The native `<hr>` element with all browser defaults reset (no margin, no border, no background-image).",
       "intrinsic": true
     }
   },
   "sizing": {
-    "background": "sys.color.scrimSubtle",
+    "background": "sys.color.border.default",
     "thickness": "sys.layout.stack.xs",
     "inlineWidth": "100%",
     "border": "none",
@@ -32,17 +32,17 @@
     "margin": "0"
   },
   "appearance": {
-    "background": "sys.color.scrimSubtle",
-    "note": "The only fill tone — Divider has no emphasis axis. Painted as a translucent ~8% inverse-tone overlay (black in light, white in dark) so the band stays visible on every host surface tier without colliding with a fixed neutral step. Mirrors the `scrimSubtle` contract used by Banner default, Chip / Tag default, Progress track, StatusTag neutral, and Skeleton."
+    "background": "sys.color.border.default",
+    "note": "The only fill tone — Divider has no emphasis axis. Painted as a translucent ~8% inverse-tone overlay (black in light, white in dark) so the band stays visible on every host surface tier without colliding with a fixed neutral step. Mirrors the `border.default` contract used by Banner default, Chip / Tag default, Progress track, StatusTag neutral, and Skeleton."
   },
   "behavior": {
     "ariaHidden": "Defaults to `aria-hidden=\"true\"` because the band is decorative chrome — screen-reader users navigate by headings and landmarks, not visual breaks.",
     "fullBleed": "Inline width is 100% of the host's content box. Divider claims the page rail in full and must not be wrapped in a padding-inline container — the band reading edge-to-edge IS what makes it a region boundary.",
-    "thicknessFixed": "Block thickness is fixed at `sys.layout.stack.xs` (8) and is not a prop. Heavier bands would compete with content; thinner bands collapse to a hairline (use the host's own `outlineVariant` border for row-level breaks, not Divider)."
+    "thicknessFixed": "Block thickness is fixed at `sys.layout.stack.xs` (8) and is not a prop. Heavier bands would compete with content; thinner bands collapse to a hairline (use the host's own `border.default` border for row-level breaks, not Divider)."
   },
   "forbidden": [
-    "divider used as a row separator inside a List — the list's own `divider={true}` paints those as a hairline `outlineVariant` rule",
-    "divider painted with `outlineVariant` / a fixed neutral step instead of `sys.color.scrimSubtle` — fixed steps collide with the surface ladder and the divider stops reading on raised surfaces",
+    "divider used as a row separator inside a List — the list's own `divider={true}` paints those as a hairline `border.default` rule",
+    "divider painted with `border.default` / a fixed neutral step instead of `sys.color.border.default` — fixed steps collide with the surface ladder and the divider stops reading on raised surfaces",
     "divider wrapped in a padding-inline div or `style={{ marginInline }}` — Divider is full-bleed and must touch the page edge to read as a region boundary",
     "divider given outer `margin-block` / surrounding `padding-block` to fake more breathing — the 8 thickness is the breathing, and the parent column never pays a gap around Divider",
     "divider painted with a corner radius or stroke — the band is a paint, not a card",

package/agents/components/empty-state/empty-state.family.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "../../family.schema.json",
+  "family": "empty-state",
+  "name": "EmptyState",
+  "description": "No-data placeholder — the centered composition a surface paints when it has no content yet (an empty feed, a search with no results, a fresh inbox). Fills the space the real data would occupy with an optional monochrome illustration, a required headline, optional body copy, and an optional primary CTA that performs the one action that would fill the surface. Single-spec family. Distinct from `skeleton` (in-flight tonal placeholder for data that is loading) — EmptyState is the durable 'there is nothing here yet, here is how to start' surface.",
+  "useCases": [
+    "surface with no data yet",
+    "empty feed / inbox / list",
+    "search with no results",
+    "first-run / zero state",
+    "cleared / dismissed-everything state"
+  ],
+  "visualReuse": "open",
+  "layoutInset": "inline",
+  "spec": "empty-state.md",
+  "usage": {
+    "note": "Headline is the `headline` prop (required); `body` is the `body` prop; the CTA is the `action` object ({ label, href?/onClick? }) which renders a default-size primary Button — there is NO `cta` slot to fill with your own button. Pass an icon node to `illustration`.",
+    "example": "<EmptyState illustration={<ChatIcon />} headline=\"No posts yet\" body=\"Conversations you start or join will appear here.\" action={{ label: 'Start a post', onClick: () => {} }} />"
+  },
+  "subcomponents": [
+    {
+      "slug": "empty-state",
+      "spec": "empty-state.spec.json",
+      "md": "empty-state.md",
+      "default": true
+    }
+  ]
+}

package/agents/components/empty-state/empty-state.md

@@ -0,0 +1,69 @@
+# EmptyState
+
+> 🇰🇷 한국어: [`i18n/ko/schema/components/empty-state/empty-state.md`](../../../i18n/ko/schema/components/empty-state/empty-state.md)
+
+The centered composition a surface paints when it holds no data yet — an optional monochrome illustration, a required headline, optional body copy, and an optional primary CTA that performs the one action that fills the surface.
+
+**Reach for this when** a feed, list, inbox, or search result would otherwise paint blank — a fresh account's empty feed, a search returning nothing, a notifications surface with nothing unread. **Skip when** the data is still loading (use [Skeleton](../skeleton/skeleton.md) — an in-flight tonal placeholder) or when the message is a transient confirmation (use [Toast](../toast/toast.md)).
+
+**Layout inset.** inline — EmptyState ships no surface fill or chrome of its own and claims no page rail. It centers its column inside the host surface that would otherwise hold the data; the host supplies the surface tier and the bounding box. The surrounding inset is the host's responsibility.
+
+## Default
+
+The full composition — illustration, headline, body, and a primary CTA. Three lines of copy at most: what the surface is for, why it is empty, and the one action that fills it. The CTA is the surface's primary action, composed as a default-size primary [Button](../button/button.md).
+
+```preview
+empty-state/default
+---
+import { EmptyState } from '@teamblind-chorus/ui';
+import { ChatIcon } from '@teamblind-chorus/ui/icons';
+
+<EmptyState
+  illustration={<ChatIcon />}
+  headline="No posts yet"
+  body="Conversations you start or join will appear here."
+  action={{ label: 'Start a post', onClick: () => {} }}
+/>
+```
+
+## No illustration
+
+The illustration is optional — omit it for a tighter, text-led zero state where a glyph would add nothing. The headline still leads; the body and CTA follow the same stack rhythm.
+
+```preview
+empty-state/no-illustration
+---
+import { EmptyState } from '@teamblind-chorus/ui';
+
+<EmptyState
+  headline="No results"
+  body="No channels match that search. Try a different keyword."
+  action={{ label: 'Clear search', onClick: () => {} }}
+/>
+```
+
+## Slots
+
+- **container** — centered flex column holding the whole composition. `align-items: center`, `text-align: center`. No surface fill of its own. `role="status"` so the empty state is announced without yanking focus.
+- **illustration** *(optional)* — centered glyph / illustration above the headline. `ref.space.600` (48) box, painted monochrome in `sys.color.text.subtle`.
+- **headline** — required lead line. `sys.typo.heading.sm` / `sys.color.text.default`.
+- **body** *(optional)* — supporting line below the headline. `sys.typo.body.sm` / `sys.color.text.subtle`.
+- **action** *(optional)* — the primary CTA, composed from the `action` object as a default-size primary [Button](../button/button.md). There is no free `cta` slot.
+
+## Anatomy
+
+| Slot         | Token bindings |
+|--------------|----------------|
+| container    | Centered flex column, `align-items: center`, `text-align: center`, no fill; `role="status"` |
+| illustration | `ref.space.600` (48 × 48) box, `sys.color.text.subtle` (`currentColor`), `sys.layout.stack.sm` (12) below it to the headline |
+| headline     | `sys.typo.heading.sm`, `sys.color.text.default` |
+| body         | `sys.typo.body.sm`, `sys.color.text.subtle`, `sys.layout.stack.2xs` (4) above it from the headline |
+| action       | Default-size primary [Button](../button/button.md), `sys.layout.stack.md` (16) above it from the body |
+
+## Behavior
+
+- **Centered in the host.** The composition is centered block + inline inside the surface that would otherwise hold the data. EmptyState owns no surface fill — the host supplies the surface tier and bounding box.
+- **Headline required, the rest optional.** Only the headline is required. The illustration, body, and CTA fill in as the copy needs them.
+- **Three lines of copy, one action.** Headline + body read as at most three lines (what the surface is for · why it is empty · the one action that fills it). The CTA is that one action.
+- **CTA is composed, not slotted.** Pass `action={{ label, href?/onClick? }}` — EmptyState renders the default-size primary Button so the fill action always reads as primary.
+- **Not a loading state.** For data that is still arriving, reach for [Skeleton](../skeleton/skeleton.md); EmptyState is the durable no-data surface.

package/agents/components/empty-state/empty-state.spec.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "EmptyState",
+  "family": "empty-state",
+  "description": "The centered composition a surface paints when it holds no data yet — an optional monochrome illustration, a required headline, optional body copy, and an optional primary CTA — stacked and centered inside the space the real content would occupy. Three lines of copy at most: what the surface is for, why it is empty, and the one action that fills it (the CTA). Reach for it whenever a feed, list, inbox, or search result would otherwise paint blank; the system hard-rule forbids leaving a no-data surface empty. Distinct from Skeleton (an in-flight tonal placeholder for data that is loading), this is the durable zero-state surface.",
+  "element": "div",
+  "props": {
+    "illustration": {
+      "type": "node",
+      "optional": true,
+      "description": "Optional leading glyph or illustration, centered above the headline. Sized to a `ref.space.600` (48) box — larger than `sys.icon.lg` (24), realizing DESIGN.md's `icon.xl` or larger intent (no `icon.xl` icon-size rung exists; the icon scale stops at `lg`). Painted in `sys.color.text.subtle` via `currentColor` so it reads as quiet, monochrome chrome — illustrations stay monochrome unless they carry deliberate brand-moment intent. Separated from the headline by `sys.layout.stack.sm` (12)."
+    },
+    "headline": {
+      "type": "node",
+      "required": true,
+      "description": "The required lead line. `sys.typo.heading.sm` in `sys.color.text.default`. Names what the surface is for / why it is empty in one short line (e.g. 'No posts yet')."
+    },
+    "body": {
+      "type": "node",
+      "optional": true,
+      "description": "Optional supporting line below the headline. `sys.typo.body.sm` in `sys.color.text.subtle`, separated from the headline by `sys.layout.stack.2xs` (4). One sentence — the second of the three lines (e.g. 'Conversations you start or join will appear here')."
+    },
+    "action": {
+      "type": "object",
+      "optional": true,
+      "description": "{ label, href?, onClick? } — the primary CTA. Renders a default-size primary `Button` (the surface's primary action — the one thing that fills the empty surface). Placed below the body with a `sys.layout.stack.md` (16) gap. There is NO `cta` slot to fill with a custom button; pass the action object so the primary Button is composed for you."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Centered flex column holding the whole composition. `align-items: center`, `text-align: center`. Ships no surface fill or chrome of its own — it sits inside the host surface that would otherwise hold the data. `role='status'` so assistive tech announces the empty state without yanking focus.",
+      "intrinsic": true
+    },
+    "illustration": {
+      "required": false,
+      "description": "Optional centered glyph / illustration above the headline. `ref.space.600` (48) box, painted in `sys.color.text.subtle` (monochrome). `sys.layout.stack.sm` (12) below it to the headline.",
+      "accepts": ["icon"]
+    },
+    "headline": {
+      "required": true,
+      "description": "Required headline line. `sys.typo.heading.sm` / `sys.color.text.default`.",
+      "accepts": ["text"]
+    },
+    "body": {
+      "required": false,
+      "description": "Optional supporting line. `sys.typo.body.sm` / `sys.color.text.subtle`. `sys.layout.stack.2xs` (4) above it from the headline.",
+      "accepts": ["text"]
+    },
+    "action": {
+      "required": false,
+      "description": "Optional primary CTA. A default-size primary `Button` composed from the `action` object. `sys.layout.stack.md` (16) above it from the body.",
+      "accepts": ["button"]
+    }
+  },
+  "sizing": {
+    "containerAlign": "center",
+    "illustrationSize": "ref.space.600",
+    "illustrationColor": "sys.color.text.subtle",
+    "illustrationGap": "sys.layout.stack.sm",
+    "headlineTypo": "sys.typo.heading.sm",
+    "headlineColor": "sys.color.text.default",
+    "bodyTypo": "sys.typo.body.sm",
+    "bodyColor": "sys.color.text.subtle",
+    "bodyGap": "sys.layout.stack.2xs",
+    "actionGap": "sys.layout.stack.md"
+  },
+  "appearance": {
+    "illustration": "sys.color.text.subtle",
+    "headline": "sys.color.text.default",
+    "body": "sys.color.text.subtle",
+    "note": "No emphasis axis — EmptyState has one quiet appearance. The illustration and body sit in the muted `onSurfaceVariant` tone; the headline steps up to `onSurface`. The only chromatic emphasis is the CTA, which is a primary `Button` (its own `sys.color.background.primary` fill) so the single fill-the-surface action reads as primary both in intent and visually."
+  },
+  "behavior": {
+    "centered": "The whole composition is centered (block + inline) inside the host surface that would otherwise hold the data. EmptyState owns no surface fill — the host supplies the surface tier and the bounding box; EmptyState only centers its column inside it.",
+    "role": "Container carries `role='status'` so the empty state is announced to assistive tech without grabbing focus.",
+    "ctaComposition": "The CTA is not a free slot — pass `action={{ label, href?/onClick? }}` and EmptyState composes a default-size primary Button. This keeps the 'one primary action' rule enforced (one CTA, primary appearance) rather than letting callers drop in an arbitrary control."
+  },
+  "forbidden": [
+    "a no-data surface left blank — every empty surface paints an EmptyState (illustration optional, headline + the one fill action required by the copy rule); the system hard-rule forbids an unaddressed empty surface",
+    "a dead-end empty state with no path forward — when the surface has a fill action, omit neither the body's explanation nor the `action` CTA; do not strand the user on a blank wall with only a headline",
+    "more than three lines of copy — headline + body must read as at most three lines total (what the surface is for · why it is empty · the one action that fills it); longer prose belongs in a Banner or a help surface",
+    "the CTA rendered as anything but a default-size primary Button — the fill action is the surface's primary action and must read as primary; do not down-rank it to a text or outlined button, and do not render two competing CTAs",
+    "EmptyState used as a loading placeholder for data that is still arriving — that is `skeleton` (an in-flight tonal block). EmptyState is the durable no-data surface, not a transient one",
+    "the illustration painted in a chromatic tone for non-brand empty states — it stays monochrome `sys.color.text.subtle` unless it deliberately carries a brand moment"
+  ]
+}

package/agents/components/feed/ad.md

@@ -34,9 +34,7 @@ import { FeedAd } from '@teamblind-chorus/ui';
 />
 ```
 
-## Use cases
-
-### With dismiss
+## Dismiss
 
 Wire `onDismiss` to render the trailing close icon for placements that give the reader a dismiss path.
 
@@ -80,7 +78,7 @@ import { FeedAd } from '@teamblind-chorus/ui';
 | title → body     | 8px vertical gap (`sys.layout.stack.xs`) |
 | title            | `heading.sm` (16 / Semibold), `onSurface`, single-line truncate |
 | body             | 14 / Regular, `onSurfaceVariant`, two-line clamp |
-| bottom divider   | `sys.borderWidth.hairline` × `sys.color.outlineVariant` — `border-bottom` on the card so a sponsored placement drops into a Post stream without breaking the inter-card seam rhythm. |
+| bottom divider   | `sys.borderWidth.hairline` × `sys.color.border.default` — `border-bottom` on the card so a sponsored placement drops into a Post stream without breaking the inter-card seam rhythm. |
 | cta-group        | `radius.md` (8px) clip wrapping media + CTA, `overflow: hidden`, no internal gap |
 | media            | Full inline width, 16:10 aspect ratio, no own radius (the group clips). Runtime fallback when `src` is missing or fails to load: `background-image: url('/placeholder.png')` over a `surfaceContainerHigh` base. |
 | cta              | [Standard Button](../button/standard.md) — `fullWidth`, `medium`, `primary` by default, **`border-radius: 0`** so the squared bottom edge meets the group's clip. `cta.color` overrides the surface fill with a free-form Hex. |

package/agents/components/feed/ad.spec.json

@@ -126,7 +126,7 @@
     }
   },
   "sizing": {
-    "containerFill": "sys.color.surface",
+    "containerFill": "sys.color.surface.default",
     "containerPaddingBlock": "sys.layout.container.lg",
     "containerPaddingInline": "sys.layout.container.md",
     "containerRadius": "sys.radius.md",
@@ -134,24 +134,24 @@
     "brandRowGap": "sys.layout.inline.md",
     "brandAvatarSize": 32,
     "brandNameTypo": "sys.typo.label.md",
-    "brandNameColor": "sys.color.onSurface",
+    "brandNameColor": "sys.color.text.default",
     "brandSubtitleTypo": "sys.typo.label.sm",
-    "brandSubtitleColor": "sys.color.onSurfaceVariant",
+    "brandSubtitleColor": "sys.color.text.subtle",
     "brandSubtitleDefault": "Sponsored",
     "dismissIconSize": "sys.icon.md",
-    "dismissColor": "sys.color.onSurfaceVariant",
+    "dismissColor": "sys.color.text.subtle",
     "dismissHitArea": 24,
     "titleTypo": "sys.typo.heading.sm",
-    "titleColor": "sys.color.onSurface",
+    "titleColor": "sys.color.text.default",
     "containerBottomDividerWidth": "sys.borderWidth.hairline",
-    "containerBottomDividerColor": "sys.color.outlineVariant",
+    "containerBottomDividerColor": "sys.color.border.default",
     "bodyTypo": "sys.typo.body.sm",
-    "bodyColor": "sys.color.onSurfaceVariant",
+    "bodyColor": "sys.color.text.subtle",
     "bodyLineClamp": 2,
     "titleBodyGap": "sys.layout.stack.xs",
     "ctaGroupRadius": "sys.radius.md",
     "mediaAspectRatio": "16 / 10",
-    "mediaFallbackFill": "sys.color.surfaceContainerHigh",
+    "mediaFallbackFill": "sys.color.surface.sunken",
     "mediaFallbackImage": "/placeholder.png",
     "mediaFallbackImageRendering": "background-image, cover, center — sits under the runtime <img>; visible only when the inline image is missing or fails to load, so the hero block still resolves to an image rather than an empty surface tone.",
     "ctaAppearance": "primary",
@@ -168,13 +168,13 @@
     "composition": "inward"
   },
   "behavior": {
-    "brandNameRequired": "Every FeedAd MUST carry an explicit `brand.name`. Lovable / mock generators must never drop it — the row is the ad's legal attribution surface, and a placement without a brand name is not a valid FeedAd.",
+    "brandNameRequired": "Every FeedAd MUST carry an explicit `brand.name`. consumers and mock generators must never drop it — the row is the ad's legal attribution surface, and a placement without a brand name is not a valid FeedAd.",
     "mediaRequired": "Every FeedAd MUST carry a hero `media` block with a non-empty `src`. The `surfaceContainerHigh` fallback is a runtime safety net for load failures, not a design-time omission — at scaffold time, use the bundled `/placeholder.png` rather than omitting `media`.",
     "brandSubtitleAlwaysPresent": "The brand subtitle defaults to `Sponsored` so every placement reads as sponsored content. Consumers may override the copy but cannot omit the row.",
     "ctaGroupBondsMediaAndCta": "Hero media and the CTA share a `radius.md` clip with no internal gap; the CTA's own `border-radius` is zeroed so its squared bottom edge meets the group's outer round.",
     "ctaColorIsFreeFormHex": "`cta.color` accepts any Hex string supplied by the ad client. Only the button surface fill and border swap — typography, size, and full-width geometry stay on the Standard Button tokens.",
     "slotOmissionCollapses": "`title`, `body`, and `dismiss` are opt-in — when any is absent the layout reflows without reserved whitespace. `brand.name` and `media` are required and may NOT be omitted.",
-    "containerBottomDivider": "Each Ad card carries the same hairline bottom divider as a Post (`sys.borderWidth.hairline` × `sys.color.outlineVariant`) so a sponsored placement drops into a Post stream without breaking the inter-card seam rhythm.",
+    "containerBottomDivider": "Each Ad card carries the same hairline bottom divider as a Post (`sys.borderWidth.hairline` × `sys.color.border.default`) so a sponsored placement drops into a Post stream without breaking the inter-card seam rhythm.",
     "truncationNotWrap": "`title` truncates; `body` clamps to two lines.",
     "dismissOptIn": "Default placements omit the trailing X; it only renders when `onDismiss` is wired.",
     "ctaCommitsAlone": "FeedAd has no engagement row. The cta-group, when present, carries a single full-width Standard Button — never two CTAs."