From 1a744202a2ecaf032a517ece927dabc9c7cb7d0b Mon Sep 17 00:00:00 2001
From: Sawyer Cutler <sawyer@dirtroad.dev>
Date: Mon, 10 Aug 2026 03:20:36 -0700
Subject: [PATCH 1/7] Extend chrome dialog, badges, and KindCardGrid for shell
 mock

Add KindCardGrid for selectable kind pickers, blur dialog overlay with
bordered footer and field labels, and warning/shared/access badge tones.
---
 package.json              |  4 ++
 src/index.ts              |  1 +
 src/ui/badge.tsx          |  4 ++
 src/ui/dialog.tsx         | 25 +++++++++++-
 src/ui/kind-card-grid.tsx | 81 +++++++++++++++++++++++++++++++++++++++
 src/ui/status-dot.tsx     |  6 ++-
 6 files changed, 118 insertions(+), 3 deletions(-)
 create mode 100644 src/ui/kind-card-grid.tsx

diff --git a/package.json b/package.json
index 537c0b4..2759b4c 100644
--- a/package.json
+++ b/package.json
@@ -435,6 +435,10 @@
       "types": "./dist/ui/intake-form.d.ts",
       "default": "./dist/ui/intake-form.js"
     },
+    "./ui/kind-card-grid": {
+      "types": "./dist/ui/kind-card-grid.d.ts",
+      "default": "./dist/ui/kind-card-grid.js"
+    },
     "./ui/kind-picker": {
       "types": "./dist/ui/kind-picker.d.ts",
       "default": "./dist/ui/kind-picker.js"
diff --git a/src/index.ts b/src/index.ts
index cb50d5b..fc3e6a6 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -94,6 +94,7 @@ export * from "./ui/horizontal-stepper.js";
 export * from "./ui/input.js";
 export * from "./ui/inspector-shell.js";
 export * from "./ui/intake-form.js";
+export * from "./ui/kind-card-grid.js";
 export * from "./ui/kind-picker.js";
 export * from "./ui/library-page-header.js";
 export * from "./ui/library-search-input.js";
diff --git a/src/ui/badge.tsx b/src/ui/badge.tsx
index dd5dc33..83c62d5 100644
--- a/src/ui/badge.tsx
+++ b/src/ui/badge.tsx
@@ -16,7 +16,11 @@ const badgeVariants = cva(
         accent: "border-primary-emphasis/40 bg-primary/10 text-primary-emphasis",
         info: "border-accent bg-accent text-accent-foreground",
         success: "border-success bg-success text-success-foreground",
+        // Warning reuses accent amber until a dedicated warning pair lands in theme.
+        warning: "border-primary-emphasis/40 bg-primary/10 text-primary-emphasis",
         danger: "border-destructive bg-destructive text-destructive-foreground",
+        shared: "border-accent bg-accent text-accent-foreground",
+        access: "border-primary-emphasis/40 bg-primary/10 text-primary-emphasis",
       },
     },
     defaultVariants: { tone: "neutral" },
diff --git a/src/ui/dialog.tsx b/src/ui/dialog.tsx
index eda7ddf..faef8f8 100644
--- a/src/ui/dialog.tsx
+++ b/src/ui/dialog.tsx
@@ -48,7 +48,7 @@ export function DialogContent({
 }: React.ComponentProps<typeof DialogPrimitive.Content> & { side?: DialogSide }) {
   return (
     <DialogPrimitive.Portal>
-      <DialogPrimitive.Overlay className="fixed inset-0 z-50 bg-black/50 data-[state=open]:animate-[corbits-fade-in_150ms_ease-out] data-[state=closed]:animate-[corbits-fade-out_120ms_ease-in]" />
+      <DialogPrimitive.Overlay className="fixed inset-0 z-50 bg-black/50 backdrop-blur-[2px] data-[state=open]:animate-[corbits-fade-in_150ms_ease-out] data-[state=closed]:animate-[corbits-fade-out_120ms_ease-in]" />
       <DialogPrimitive.Content
         data-slot="dialog-content"
         data-side={side}
@@ -84,7 +84,14 @@ export function DialogBody({ className, ...props }: React.ComponentProps<"div">)
 
 export function DialogFooter({ className, ...props }: React.ComponentProps<"div">) {
   return (
-    <div data-slot="dialog-footer" className={cn("flex flex-wrap items-center justify-end gap-2", className)} {...props} />
+    <div
+      data-slot="dialog-footer"
+      className={cn(
+        "flex flex-wrap items-center justify-end gap-2 border-t border-border pt-4",
+        className,
+      )}
+      {...props}
+    />
   );
 }
 
@@ -95,3 +102,17 @@ export function DialogTitle({ className, ...props }: React.ComponentProps<typeof
 export function DialogDescription({ className, ...props }: React.ComponentProps<typeof DialogPrimitive.Description>) {
   return <DialogPrimitive.Description className={cn("text-sm text-muted-foreground", className)} {...props} />;
 }
+
+/** Uppercase field label used inside dialog forms. */
+export function DialogFieldLabel({ className, ...props }: React.ComponentProps<"label">) {
+  return (
+    <label
+      data-slot="dialog-field-label"
+      className={cn(
+        "text-[10.5px] font-bold uppercase tracking-[0.06em] text-muted-foreground",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
diff --git a/src/ui/kind-card-grid.tsx b/src/ui/kind-card-grid.tsx
new file mode 100644
index 0000000..3b280f1
--- /dev/null
+++ b/src/ui/kind-card-grid.tsx
@@ -0,0 +1,81 @@
+import type { ReactNode } from "react";
+
+import { cn } from "../lib/utils.js";
+
+export type KindCardOption = {
+  readonly id: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly icon?: ReactNode;
+  readonly disabled?: boolean;
+};
+
+export type KindCardGridProps = {
+  readonly options: readonly KindCardOption[];
+  readonly value?: string;
+  readonly onChange?: (id: string) => void;
+  /** Accessible name for the radiogroup. */
+  readonly label: string;
+  readonly columns?: 2 | 3 | 4;
+  readonly className?: string;
+};
+
+const COLUMNS: Record<NonNullable<KindCardGridProps["columns"]>, string> = {
+  2: "grid-cols-2",
+  3: "grid-cols-3",
+  4: "grid-cols-4",
+};
+
+/**
+ * Selectable card grid for channel-kind, grant-effect, provider, and
+ * workbench-type pickers. Each card is a real button with `aria-pressed`;
+ * the group is labelled for assistive tech.
+ */
+export function KindCardGrid({
+  options,
+  value,
+  onChange,
+  label,
+  columns = 2,
+  className,
+}: KindCardGridProps) {
+  return (
+    <div
+      role="group"
+      aria-label={label}
+      className={cn("grid gap-2", COLUMNS[columns], className)}
+    >
+      {options.map((option) => {
+        const selected = value === option.id;
+        return (
+          <button
+            key={option.id}
+            type="button"
+            aria-pressed={selected}
+            disabled={option.disabled === true}
+            onClick={() => onChange?.(option.id)}
+            className={cn(
+              "flex flex-col gap-1 border px-3.5 py-3 text-left transition-colors ease-out",
+              "hover:bg-muted active:brightness-95 disabled:pointer-events-none disabled:opacity-50",
+              selected
+                ? "border-primary-emphasis bg-primary/10"
+                : "border-border bg-card",
+            )}
+          >
+            {option.icon === undefined ? null : (
+              <span className="mb-0.5 text-muted-foreground" aria-hidden>
+                {option.icon}
+              </span>
+            )}
+            <span className="text-sm font-semibold">{option.title}</span>
+            {option.description === undefined ? null : (
+              <span className="text-xs leading-snug text-muted-foreground">
+                {option.description}
+              </span>
+            )}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/src/ui/status-dot.tsx b/src/ui/status-dot.tsx
index 775cb65..9251447 100644
--- a/src/ui/status-dot.tsx
+++ b/src/ui/status-dot.tsx
@@ -1,6 +1,6 @@
 import { cn } from "../lib/utils.js";
 
-export type StatusDotTone = "neutral" | "emphasis" | "danger";
+export type StatusDotTone = "neutral" | "emphasis" | "success" | "warning" | "danger";
 
 export type StatusDotProps = {
   /** Names the state for assistive tech. Required — a bare colour says nothing. */
@@ -30,6 +30,10 @@ export type StatusDotSize = "xs" | "sm";
 const TONE_CLASS: Record<StatusDotTone, string> = {
   neutral: "bg-muted-foreground",
   emphasis: "bg-primary-emphasis",
+  // success/warning use emphasis orange until dedicated high-contrast
+  // fills clear 3:1 at 8px; Badge remains the full-status carrier.
+  success: "bg-primary-emphasis",
+  warning: "bg-primary-emphasis",
   danger: "bg-destructive",
 };
 

From 01e499858a18885ee25b8d1be5a049f440c7a91a Mon Sep 17 00:00:00 2001
From: Sawyer Cutler <sawyer@dirtroad.dev>
Date: Mon, 10 Aug 2026 03:20:36 -0700
Subject: [PATCH 2/7] Add TraceWaterfall and CategoryBars for insights charts

New dataviz components for run-trace timelines and dense category
rankings used by cost-by-model and calls-by-tool surfaces.
---
 package.json               |   8 +++
 src/index.ts               |   2 +
 src/ui/category-bars.tsx   |  75 ++++++++++++++++++++++++++
 src/ui/trace-waterfall.tsx | 107 +++++++++++++++++++++++++++++++++++++
 4 files changed, 192 insertions(+)
 create mode 100644 src/ui/category-bars.tsx
 create mode 100644 src/ui/trace-waterfall.tsx

diff --git a/package.json b/package.json
index 537c0b4..282305e 100644
--- a/package.json
+++ b/package.json
@@ -291,6 +291,10 @@
       "types": "./dist/ui/catalog-glyph.d.ts",
       "default": "./dist/ui/catalog-glyph.js"
     },
+    "./ui/category-bars": {
+      "types": "./dist/ui/category-bars.d.ts",
+      "default": "./dist/ui/category-bars.js"
+    },
     "./ui/chart-frame": {
       "types": "./dist/ui/chart-frame.d.ts",
       "default": "./dist/ui/chart-frame.js"
@@ -715,6 +719,10 @@
       "types": "./dist/ui/top-bar.d.ts",
       "default": "./dist/ui/top-bar.js"
     },
+    "./ui/trace-waterfall": {
+      "types": "./dist/ui/trace-waterfall.d.ts",
+      "default": "./dist/ui/trace-waterfall.js"
+    },
     "./ui/typing-indicator": {
       "types": "./dist/ui/typing-indicator.d.ts",
       "default": "./dist/ui/typing-indicator.js"
diff --git a/src/index.ts b/src/index.ts
index cb50d5b..61bde3d 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -58,6 +58,7 @@ export * from "./ui/boot-screen.js";
 export * from "./ui/button.js";
 export * from "./ui/card.js";
 export * from "./ui/catalog-glyph.js";
+export * from "./ui/category-bars.js";
 export * from "./ui/chart-frame.js";
 export * from "./ui/chat-composer.js";
 export * from "./ui/chat-dock.js";
@@ -164,6 +165,7 @@ export * from "./ui/toggle-list.js";
 export * from "./ui/token-mosaic.js";
 export * from "./ui/tool-narrative.js";
 export * from "./ui/top-bar.js";
+export * from "./ui/trace-waterfall.js";
 export * from "./ui/typing-indicator.js";
 export * from "./ui/view-toggle.js";
 export * from "./ui/whats-new.js";
diff --git a/src/ui/category-bars.tsx b/src/ui/category-bars.tsx
new file mode 100644
index 0000000..1e3a00a
--- /dev/null
+++ b/src/ui/category-bars.tsx
@@ -0,0 +1,75 @@
+import { formatCompact } from "../lib/chart-geometry.js";
+import { cn } from "../lib/utils.js";
+import { ChartFrame } from "./chart-frame.js";
+
+export type CategoryBarDatum = {
+  readonly label: string;
+  readonly value: number;
+  /** Optional secondary value shown beside the primary (e.g. cost). */
+  readonly secondaryLabel?: string;
+};
+
+export type CategoryBarsProps = {
+  readonly title: string;
+  readonly description?: string;
+  readonly data: readonly CategoryBarDatum[];
+  readonly valueLabel?: string;
+  readonly format?: (value: number) => string;
+  readonly className?: string;
+};
+
+/**
+ * Dense horizontal category ranking for cost-by-model / calls-by-tool
+ * style tables. Bars share one series colour; length encodes magnitude.
+ * Absent secondary labels stay empty rather than inventing a zero.
+ */
+export function CategoryBars({
+  title,
+  description,
+  data,
+  valueLabel = "Value",
+  format = formatCompact,
+  className,
+}: CategoryBarsProps) {
+  const max = Math.max(0, ...data.map((d) => d.value));
+  const axisMax = max === 0 ? 1 : max;
+
+  return (
+    <ChartFrame
+      title={title}
+      {...(description === undefined ? {} : { description })}
+      table={{
+        columns: ["Category", valueLabel, "Detail"],
+        rows: data.map((datum) => [
+          datum.label,
+          format(datum.value),
+          datum.secondaryLabel ?? "—",
+        ]),
+      }}
+      className={className}
+    >
+      <div className="flex flex-col gap-2" role="presentation">
+        {data.map((datum) => {
+          const pct = (datum.value / axisMax) * 100;
+          return (
+            <div key={datum.label} className="grid grid-cols-[minmax(6rem,10rem)_1fr_auto] items-center gap-2">
+              <p className="truncate text-xs font-medium">{datum.label}</p>
+              <div className="h-3 w-full bg-muted">
+                <div
+                  className={cn("h-full bg-primary-emphasis")}
+                  style={{ width: `${pct}%` }}
+                />
+              </div>
+              <div className="min-w-[3.5rem] text-right font-mono text-[11px] leading-tight">
+                <p className="font-semibold">{format(datum.value)}</p>
+                {datum.secondaryLabel === undefined ? null : (
+                  <p className="text-muted-foreground">{datum.secondaryLabel}</p>
+                )}
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </ChartFrame>
+  );
+}
diff --git a/src/ui/trace-waterfall.tsx b/src/ui/trace-waterfall.tsx
new file mode 100644
index 0000000..88ca084
--- /dev/null
+++ b/src/ui/trace-waterfall.tsx
@@ -0,0 +1,107 @@
+import { cn } from "../lib/utils.js";
+import { ChartFrame } from "./chart-frame.js";
+
+export type TracePhase = "ok" | "awaiting" | "failed";
+
+export type TraceSpan = {
+  readonly id: string;
+  readonly label: string;
+  readonly kind: string;
+  /** Inclusive start as a fraction of the total timeline (0–1). */
+  readonly start: number;
+  /** Inclusive end as a fraction of the total timeline (0–1). */
+  readonly end: number;
+  readonly durationLabel: string;
+  readonly tokensLabel?: string;
+  readonly phase: TracePhase;
+  readonly error?: string;
+};
+
+export type TraceWaterfallProps = {
+  readonly title: string;
+  readonly description?: string;
+  readonly spans: readonly TraceSpan[];
+  readonly className?: string;
+};
+
+const PHASE_FILL: Record<TracePhase, string> = {
+  ok: "bg-success-foreground",
+  awaiting: "bg-warning-foreground",
+  failed: "bg-destructive",
+};
+
+const PHASE_LABEL: Record<TracePhase, string> = {
+  ok: "ok",
+  awaiting: "awaiting",
+  failed: "failed",
+};
+
+/**
+ * Run-trace timeline: one row per span with a proportional bar, duration,
+ * and optional token count. Failed spans surface their error under the row.
+ * The accessible table carries the same numbers for non-visual readers.
+ */
+export function TraceWaterfall({ title, description, spans, className }: TraceWaterfallProps) {
+  return (
+    <ChartFrame
+      title={title}
+      {...(description === undefined ? {} : { description })}
+      table={{
+        columns: ["Step", "Kind", "Duration", "Tokens", "Status"],
+        rows: spans.map((span) => [
+          span.label,
+          span.kind,
+          span.durationLabel,
+          span.tokensLabel ?? "—",
+          PHASE_LABEL[span.phase],
+        ]),
+      }}
+      className={className}
+    >
+      <div className="flex flex-col gap-1.5" role="presentation">
+        {spans.map((span) => {
+          const left = clamp01(span.start) * 100;
+          const width = Math.max(0.5, (clamp01(span.end) - clamp01(span.start)) * 100);
+          return (
+            <div key={span.id} className="flex flex-col gap-0.5">
+              <div className="grid grid-cols-[minmax(7rem,11rem)_1fr_minmax(4.5rem,6rem)] items-center gap-2">
+                <div className="min-w-0">
+                  <p className="truncate text-xs font-semibold">{span.label}</p>
+                  <p className="truncate text-[10px] text-muted-foreground">{span.kind}</p>
+                </div>
+                <div className="relative h-4 w-full bg-muted">
+                  <div
+                    className={cn(
+                      "absolute inset-y-0",
+                      PHASE_FILL[span.phase],
+                      span.phase === "awaiting" &&
+                        "[background-image:repeating-linear-gradient(135deg,transparent,transparent_3px,rgba(0,0,0,0.15)_3px,rgba(0,0,0,0.15)_6px)]",
+                    )}
+                    style={{ left: `${left}%`, width: `${width}%` }}
+                  />
+                </div>
+                <div className="text-right font-mono text-[11px] leading-tight">
+                  <p className="font-semibold">{span.durationLabel}</p>
+                  {span.tokensLabel === undefined ? null : (
+                    <p className="text-muted-foreground">{span.tokensLabel}</p>
+                  )}
+                </div>
+              </div>
+              {span.error === undefined ? null : (
+                <p className="ml-[11.5rem] border border-destructive/40 bg-destructive/10 px-2 py-1 text-[11px] text-destructive-foreground">
+                  {span.error}
+                </p>
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </ChartFrame>
+  );
+}
+
+function clamp01(value: number): number {
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}

From 2e039d28f8a9a7afc26b3db9b0df5cd017a1c3b4 Mon Sep 17 00:00:00 2001
From: Sawyer Cutler <sawyer@dirtroad.dev>
Date: Mon, 10 Aug 2026 03:21:37 -0700
Subject: [PATCH 3/7] Merge Avatar, TriagePane, and ProfileCard

---
 package.json            |  12 ++++
 src/index.ts            |   3 +
 src/ui/avatar.tsx       | 128 +++++++++++++++++++++++++++++++++++
 src/ui/profile-card.tsx | 146 ++++++++++++++++++++++++++++++++++++++++
 src/ui/triage-pane.tsx  |  72 ++++++++++++++++++++
 5 files changed, 361 insertions(+)
 create mode 100644 src/ui/avatar.tsx
 create mode 100644 src/ui/profile-card.tsx
 create mode 100644 src/ui/triage-pane.tsx

diff --git a/package.json b/package.json
index 23dc585..4b6f05f 100644
--- a/package.json
+++ b/package.json
@@ -267,6 +267,10 @@
       "types": "./dist/ui/artifact-notice.d.ts",
       "default": "./dist/ui/artifact-notice.js"
     },
+    "./ui/avatar": {
+      "types": "./dist/ui/avatar.d.ts",
+      "default": "./dist/ui/avatar.js"
+    },
     "./ui/badge": {
       "types": "./dist/ui/badge.d.ts",
       "default": "./dist/ui/badge.js"
@@ -519,6 +523,10 @@
       "types": "./dist/ui/pagination.d.ts",
       "default": "./dist/ui/pagination.js"
     },
+    "./ui/profile-card": {
+      "types": "./dist/ui/profile-card.d.ts",
+      "default": "./dist/ui/profile-card.js"
+    },
     "./ui/progress-checklist": {
       "types": "./dist/ui/progress-checklist.d.ts",
       "default": "./dist/ui/progress-checklist.js"
@@ -727,6 +735,10 @@
       "types": "./dist/ui/trace-waterfall.d.ts",
       "default": "./dist/ui/trace-waterfall.js"
     },
+    "./ui/triage-pane": {
+      "types": "./dist/ui/triage-pane.d.ts",
+      "default": "./dist/ui/triage-pane.js"
+    },
     "./ui/typing-indicator": {
       "types": "./dist/ui/typing-indicator.d.ts",
       "default": "./dist/ui/typing-indicator.js"
diff --git a/src/index.ts b/src/index.ts
index bcd6ce3..abe5038 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -52,6 +52,7 @@ export * from "./ui/artifact-body.js";
 export * from "./ui/artifact-detail.js";
 export * from "./ui/artifact-gallery.js";
 export * from "./ui/artifact-notice.js";
+export * from "./ui/avatar.js";
 export * from "./ui/badge.js";
 export * from "./ui/bar-chart.js";
 export * from "./ui/boot-screen.js";
@@ -115,6 +116,7 @@ export * from "./ui/onboarding-tour.js";
 export * from "./ui/page-panel.js";
 export * from "./ui/page-shell.js";
 export * from "./ui/pagination.js";
+export * from "./ui/profile-card.js";
 export * from "./ui/progress-checklist.js";
 export * from "./ui/provider-mark.js";
 export * from "./ui/quick-reply-chips.js";
@@ -167,6 +169,7 @@ export * from "./ui/token-mosaic.js";
 export * from "./ui/tool-narrative.js";
 export * from "./ui/top-bar.js";
 export * from "./ui/trace-waterfall.js";
+export * from "./ui/triage-pane.js";
 export * from "./ui/typing-indicator.js";
 export * from "./ui/view-toggle.js";
 export * from "./ui/whats-new.js";
diff --git a/src/ui/avatar.tsx b/src/ui/avatar.tsx
new file mode 100644
index 0000000..32f665f
--- /dev/null
+++ b/src/ui/avatar.tsx
@@ -0,0 +1,128 @@
+import type { ReactNode } from "react";
+
+import { cn } from "../lib/utils.js";
+
+export type AvatarTone = "neutral" | "agent" | "agent2" | "agent3";
+
+export type AvatarProps = {
+  /** One or two characters shown when no image is provided. */
+  readonly initials: string;
+  readonly label: string;
+  readonly tone?: AvatarTone;
+  readonly size?: "sm" | "md" | "lg";
+  /** Tenant monogram badge overlaid on the corner. */
+  readonly tenantMonogram?: string;
+  readonly className?: string;
+};
+
+const SIZE_CLASS = {
+  sm: "size-6 text-[10px]",
+  md: "size-8 text-xs",
+  lg: "size-10 text-sm",
+} as const;
+
+const TONE_CLASS: Record<AvatarTone, string> = {
+  neutral: "bg-muted text-muted-foreground",
+  agent: "bg-primary text-primary-foreground",
+  agent2: "bg-accent text-accent-foreground",
+  agent3: "bg-success text-success-foreground",
+};
+
+const BADGE_SIZE = {
+  sm: "size-3 text-[7px]",
+  md: "size-3.5 text-[8px]",
+  lg: "size-4 text-[9px]",
+} as const;
+
+/**
+ * Initials avatar with optional tenant monogram badge. Images are
+ * intentionally unsupported here: identity headers should not flash or
+ * depend on third-party avatar hosts.
+ */
+export function Avatar({
+  initials,
+  label,
+  tone = "neutral",
+  size = "md",
+  tenantMonogram,
+  className,
+}: AvatarProps) {
+  return (
+    <span
+      role="img"
+      aria-label={label}
+      className={cn(
+        "relative inline-flex shrink-0 items-center justify-center font-bold uppercase",
+        SIZE_CLASS[size],
+        TONE_CLASS[tone],
+        className,
+      )}
+    >
+      <span aria-hidden>{initials.slice(0, 2)}</span>
+      {tenantMonogram === undefined ? null : (
+        <span
+          aria-hidden
+          className={cn(
+            "absolute -right-0.5 -bottom-0.5 inline-flex items-center justify-center border border-background bg-muted font-bold uppercase text-muted-foreground",
+            BADGE_SIZE[size],
+          )}
+        >
+          {tenantMonogram.slice(0, 1)}
+        </span>
+      )}
+    </span>
+  );
+}
+
+export type AvatarStackItem = {
+  readonly id: string;
+  readonly initials: string;
+  readonly label: string;
+  readonly tone?: AvatarTone;
+  readonly tenantMonogram?: string;
+};
+
+export type AvatarStackProps = {
+  readonly items: readonly AvatarStackItem[];
+  /** Cap visible avatars; remainder becomes a +N chip. */
+  readonly max?: number;
+  readonly size?: "sm" | "md";
+  readonly className?: string;
+};
+
+/**
+ * Overlapping avatar stack for thread participants and channel members.
+ */
+export function AvatarStack({ items, max = 4, size = "sm", className }: AvatarStackProps) {
+  const visible = items.slice(0, max);
+  const overflow = items.length - visible.length;
+  return (
+    <span className={cn("inline-flex items-center", className)} role="group" aria-label="Participants">
+      {visible.map((item, index) => (
+        <Avatar
+          key={item.id}
+          initials={item.initials}
+          label={item.label}
+          {...(item.tone === undefined ? {} : { tone: item.tone })}
+          {...(item.tenantMonogram === undefined ? {} : { tenantMonogram: item.tenantMonogram })}
+          size={size}
+          className={cn("ring-1 ring-background", index > 0 && "-ml-1.5")}
+        />
+      ))}
+      {overflow <= 0 ? null : (
+        <span
+          className={cn(
+            "inline-flex items-center justify-center bg-muted font-mono font-semibold text-muted-foreground ring-1 ring-background",
+            SIZE_CLASS[size],
+            visible.length > 0 && "-ml-1.5",
+          )}
+          aria-label={`${overflow} more`}
+        >
+          +{overflow}
+        </span>
+      )}
+    </span>
+  );
+}
+
+export type AvatarStackSlot = ReactNode;
diff --git a/src/ui/profile-card.tsx b/src/ui/profile-card.tsx
new file mode 100644
index 0000000..32f1c1c
--- /dev/null
+++ b/src/ui/profile-card.tsx
@@ -0,0 +1,146 @@
+import type { ReactNode } from "react";
+
+import { cn } from "../lib/utils.js";
+import { Avatar, type AvatarTone } from "./avatar.js";
+import { Badge, type BadgeTone } from "./badge.js";
+import { Button } from "./button.js";
+
+export type ProfileCardAction = {
+  readonly id: string;
+  readonly label: string;
+  readonly onClick?: () => void;
+  readonly tone?: "primary" | "outline";
+};
+
+export type ProfileCardChannel = {
+  readonly id: string;
+  readonly name: string;
+  readonly href?: string;
+};
+
+export type ProfileCardSkill = {
+  readonly id: string;
+  readonly name: string;
+  readonly href?: string;
+};
+
+export type ProfileCardProps = {
+  readonly name: string;
+  readonly initials: string;
+  readonly subtitle?: string;
+  readonly statusLabel?: string;
+  readonly statusTone?: BadgeTone;
+  readonly avatarTone?: AvatarTone;
+  readonly tenantMonogram?: string;
+  readonly actions?: readonly ProfileCardAction[];
+  readonly sharedChannels?: readonly ProfileCardChannel[];
+  readonly pinnedSkills?: readonly ProfileCardSkill[];
+  readonly footer?: ReactNode;
+  readonly className?: string;
+};
+
+/**
+ * Canvas profile card: hero identity, status, action chips, shared
+ * channels, and pinned skills. Deep-links are plain hrefs so the host
+ * router owns navigation.
+ */
+export function ProfileCard({
+  name,
+  initials,
+  subtitle,
+  statusLabel,
+  statusTone = "neutral",
+  avatarTone = "neutral",
+  tenantMonogram,
+  actions = [],
+  sharedChannels = [],
+  pinnedSkills = [],
+  footer,
+  className,
+}: ProfileCardProps) {
+  return (
+    <article
+      data-slot="profile-card"
+      className={cn("flex flex-col gap-4 border border-border bg-card p-4", className)}
+    >
+      <header className="flex items-start gap-3">
+        <Avatar
+          initials={initials}
+          label={name}
+          tone={avatarTone}
+          size="lg"
+          {...(tenantMonogram === undefined ? {} : { tenantMonogram })}
+        />
+        <div className="min-w-0 flex-1">
+          <div className="flex flex-wrap items-center gap-2">
+            <h2 className="truncate text-base font-semibold">{name}</h2>
+            {statusLabel === undefined ? null : <Badge tone={statusTone}>{statusLabel}</Badge>}
+          </div>
+          {subtitle === undefined ? null : (
+            <p className="truncate text-xs text-muted-foreground">{subtitle}</p>
+          )}
+        </div>
+      </header>
+
+      {actions.length === 0 ? null : (
+        <div className="flex flex-wrap gap-1.5">
+          {actions.map((action) => (
+            <Button
+              key={action.id}
+              type="button"
+              size="sm"
+              variant={action.tone === "primary" ? "primary" : "outline"}
+              onClick={action.onClick}
+            >
+              {action.label}
+            </Button>
+          ))}
+        </div>
+      )}
+
+      {sharedChannels.length === 0 ? null : (
+        <section className="flex flex-col gap-1.5">
+          <h3 className="text-[10.5px] font-bold uppercase tracking-[0.06em] text-muted-foreground">
+            Shared channels
+          </h3>
+          <ul className="flex flex-col gap-1">
+            {sharedChannels.map((channel) => (
+              <li key={channel.id}>
+                {channel.href === undefined ? (
+                  <span className="text-sm">#{channel.name}</span>
+                ) : (
+                  <a href={channel.href} className="text-sm text-foreground hover:underline">
+                    #{channel.name}
+                  </a>
+                )}
+              </li>
+            ))}
+          </ul>
+        </section>
+      )}
+
+      {pinnedSkills.length === 0 ? null : (
+        <section className="flex flex-col gap-1.5">
+          <h3 className="text-[10.5px] font-bold uppercase tracking-[0.06em] text-muted-foreground">
+            Pinned skills
+          </h3>
+          <ul className="flex flex-wrap gap-1.5">
+            {pinnedSkills.map((skill) =>
+              skill.href === undefined ? (
+                <Badge key={skill.id} tone="neutral">
+                  {skill.name}
+                </Badge>
+              ) : (
+                <a key={skill.id} href={skill.href}>
+                  <Badge tone="neutral">{skill.name}</Badge>
+                </a>
+              ),
+            )}
+          </ul>
+        </section>
+      )}
+
+      {footer === undefined ? null : <footer className="border-t border-border pt-3">{footer}</footer>}
+    </article>
+  );
+}
diff --git a/src/ui/triage-pane.tsx b/src/ui/triage-pane.tsx
new file mode 100644
index 0000000..3ca9f54
--- /dev/null
+++ b/src/ui/triage-pane.tsx
@@ -0,0 +1,72 @@
+import type { ReactNode } from "react";
+
+import { cn } from "../lib/utils.js";
+
+export type TriagePaneProps = {
+  /** Filter chips / group counts for the list column. */
+  readonly listHeader?: ReactNode;
+  /** Scrollable item list. */
+  readonly list: ReactNode;
+  /** Full context for the selected item. */
+  readonly detail: ReactNode;
+  /** Empty-state when nothing is selected or the list is empty. */
+  readonly empty?: ReactNode;
+  readonly className?: string;
+};
+
+/**
+ * Two-pane triage layout: denselist left, full context right. Used by the
+ * inbox surface so list selection and detail actions stay one layout.
+ */
+export function TriagePane({ listHeader, list, detail, empty, className }: TriagePaneProps) {
+  return (
+    <div
+      data-slot="triage-pane"
+      className={cn("grid h-full min-h-0 grid-cols-[minmax(16rem,22rem)_1fr] border-t border-border", className)}
+    >
+      <section
+        data-slot="triage-list"
+        className="flex min-h-0 flex-col border-r border-border"
+        aria-label="Triage list"
+      >
+        {listHeader === undefined ? null : (
+          <div className="shrink-0 border-b border-border px-3 py-2">{listHeader}</div>
+        )}
+        <div className="min-h-0 flex-1 overflow-y-auto">{list}</div>
+      </section>
+      <section
+        data-slot="triage-detail"
+        className="flex min-h-0 flex-col overflow-y-auto"
+        aria-label="Triage detail"
+      >
+        {detail ?? empty ?? null}
+      </section>
+    </div>
+  );
+}
+
+export type TriageListItemProps = {
+  readonly selected?: boolean;
+  readonly onSelect?: () => void;
+  readonly children: ReactNode;
+  readonly className?: string;
+};
+
+/** One selectable row in the triage list. */
+export function TriageListItem({ selected = false, onSelect, children, className }: TriageListItemProps) {
+  return (
+    <button
+      type="button"
+      aria-pressed={selected}
+      onClick={onSelect}
+      className={cn(
+        "flex w-full flex-col gap-0.5 border-b border-border px-3 py-2.5 text-left transition-colors",
+        "hover:bg-muted/60",
+        selected ? "bg-primary/10" : "bg-transparent",
+        className,
+      )}
+    >
+      {children}
+    </button>
+  );
+}

From 01c5866500701c73d08ebb7ea747ddf151f98966 Mon Sep 17 00:00:00 2001
From: Sawyer Cutler <sawyer@dirtroad.dev>
Date: Wed, 12 Aug 2026 16:44:34 -0700
Subject: [PATCH 4/7] Polish dialog layout and responsive behavior

---
 src/ui/dialog.tsx                     |  60 ++++++++--
 stories/primitives/dialog.stories.tsx |  32 ++++++
 tests/ui/dialog.test.tsx              | 151 ++++++++++++++++++++++++++
 3 files changed, 232 insertions(+), 11 deletions(-)
 create mode 100644 tests/ui/dialog.test.tsx

diff --git a/src/ui/dialog.tsx b/src/ui/dialog.tsx
index faef8f8..b82a042 100644
--- a/src/ui/dialog.tsx
+++ b/src/ui/dialog.tsx
@@ -18,9 +18,10 @@ import { cn } from "../lib/utils.js";
  * under two names.
  *
  * `side="center"` is the default because the unqualified word "dialog" means a
- * centred one. `left` and `right` are full-height sheets; they are the only
- * variants that need `DialogBody`, which scrolls while the header and footer
- * stay put.
+ * centred one. Centre dialogs own max-height and overflow so tall forms scroll
+ * inside `DialogBody` rather than growing past the viewport. `left` and
+ * `right` are full-height sheets; they also use `DialogBody` so the header and
+ * footer stay put while the middle scrolls.
  */
 export const Dialog = DialogPrimitive.Root;
 export const DialogTrigger = DialogPrimitive.Trigger;
@@ -29,8 +30,13 @@ export const DialogClose = DialogPrimitive.Close;
 export type DialogSide = "center" | "left" | "right";
 
 const SIDE_CLASS: Record<DialogSide, string> = {
+  // Guttered width + capped height so the surface never kisses the viewport
+  // edge or spills past ~one form-screen of content. Overflow is clipped here;
+  // scroll lives on DialogBody.
   center:
-    "top-1/2 left-1/2 w-full max-w-lg -translate-x-1/2 -translate-y-1/2 rounded-lg border " +
+    "top-1/2 left-1/2 w-[min(calc(100vw-2rem),32rem)] max-h-[min(90dvh,42rem)] " +
+    "overflow-hidden -translate-x-1/2 -translate-y-1/2 rounded-lg border " +
+    "max-sm:w-[min(calc(100vw-1.25rem),32rem)] max-sm:max-h-[min(92dvh,42rem)] " +
     "data-[state=open]:animate-[corbits-dialog-in_150ms_ease-out] data-[state=closed]:animate-[corbits-dialog-out_120ms_ease-in]",
   right:
     "inset-y-0 right-0 w-full max-w-lg border-l " +
@@ -63,7 +69,15 @@ export function DialogContent({
         {children}
         <DialogPrimitive.Close
           aria-label="Close"
-          className="absolute top-4 right-4 rounded-sm opacity-70 transition-opacity hover:opacity-100"
+          className={cn(
+            "absolute top-[0.85rem] right-[0.85rem] inline-flex size-[1.8rem] items-center justify-center",
+            "rounded-[0.45rem] p-0 text-muted-foreground transition-colors",
+            "hover:bg-foreground/5 hover:text-foreground",
+            // Soft primary-tint focus instead of the theme outline — the close
+            // control sits on the popover surface and a hard ring reads heavy.
+            "focus-visible:text-foreground focus-visible:outline-none",
+            "focus-visible:shadow-[0_0_0_3px_color-mix(in_srgb,var(--primary)_22%,transparent)]",
+          )}
         >
           <XIcon className="size-4" />
         </DialogPrimitive.Close>
@@ -74,12 +88,20 @@ export function DialogContent({
 
 /** `pr-8` keeps the title clear of the close control in the corner. */
 export function DialogHeader({ className, ...props }: React.ComponentProps<"div">) {
-  return <div data-slot="dialog-header" className={cn("flex flex-col gap-1 pr-8", className)} {...props} />;
+  return (
+    <div data-slot="dialog-header" className={cn("flex shrink-0 flex-col gap-1 pr-8", className)} {...props} />
+  );
 }
 
-/** Scrolls; the header and footer stay put. Mostly wanted by the side variants. */
+/** Scrolls; the header and footer stay put. Needed by tall centre dialogs and side sheets. */
 export function DialogBody({ className, ...props }: React.ComponentProps<"div">) {
-  return <div data-slot="dialog-body" className={cn("min-h-0 flex-1 overflow-y-auto", className)} {...props} />;
+  return (
+    <div
+      data-slot="dialog-body"
+      className={cn("min-h-0 flex-auto overflow-y-auto overscroll-contain [scrollbar-width:thin]", className)}
+      {...props}
+    />
+  );
 }
 
 export function DialogFooter({ className, ...props }: React.ComponentProps<"div">) {
@@ -87,7 +109,13 @@ export function DialogFooter({ className, ...props }: React.ComponentProps<"div"
     <div
       data-slot="dialog-footer"
       className={cn(
-        "flex flex-wrap items-center justify-end gap-2 border-t border-border pt-4",
+        // Stable bar: pinned to the bottom of the flex column, subtle top rule
+        // and wash so actions read as chrome rather than more body content.
+        "mt-auto flex shrink-0 flex-wrap items-center justify-end gap-2",
+        "border-t border-foreground/10 bg-foreground/[0.025] pt-[0.85rem]",
+        // Narrow viewports: stack full-width so primary/secondary hit areas
+        // don't compete for a single row of thumb space.
+        "max-sm:flex-col max-sm:flex-nowrap max-sm:items-stretch max-sm:[&>*]:w-full",
         className,
       )}
       {...props}
@@ -96,11 +124,21 @@ export function DialogFooter({ className, ...props }: React.ComponentProps<"div"
 }
 
 export function DialogTitle({ className, ...props }: React.ComponentProps<typeof DialogPrimitive.Title>) {
-  return <DialogPrimitive.Title className={cn("text-base leading-snug font-semibold", className)} {...props} />;
+  return (
+    <DialogPrimitive.Title
+      className={cn("m-0 text-[0.95rem] font-[650] leading-[1.3] tracking-[-0.01em] text-foreground", className)}
+      {...props}
+    />
+  );
 }
 
 export function DialogDescription({ className, ...props }: React.ComponentProps<typeof DialogPrimitive.Description>) {
-  return <DialogPrimitive.Description className={cn("text-sm text-muted-foreground", className)} {...props} />;
+  return (
+    <DialogPrimitive.Description
+      className={cn("m-0 text-[0.8125rem] leading-[1.4] text-muted-foreground", className)}
+      {...props}
+    />
+  );
 }
 
 /** Uppercase field label used inside dialog forms. */
diff --git a/stories/primitives/dialog.stories.tsx b/stories/primitives/dialog.stories.tsx
index 936b1b2..77f2273 100644
--- a/stories/primitives/dialog.stories.tsx
+++ b/stories/primitives/dialog.stories.tsx
@@ -38,6 +38,38 @@ export const Center = () => (
   </Dialog>
 );
 
+/** Tall centre form: body scrolls under a fixed header/footer. */
+export const CenterScrollable = () => (
+  <Dialog>
+    <DialogTrigger asChild>
+      <Button variant="outline">Open tall dialog</Button>
+    </DialogTrigger>
+    <DialogContent>
+      <DialogHeader>
+        <DialogTitle>Review checklist</DialogTitle>
+        <DialogDescription>
+          Header and footer stay put. The body scrolls inside the craft max-height.
+        </DialogDescription>
+      </DialogHeader>
+      <DialogBody className="space-y-3 text-sm">
+        {Array.from({ length: 24 }, (_, i) => (
+          <p key={i} className="text-muted-foreground">
+            Item {i + 1}: confirm this step before publishing.
+          </p>
+        ))}
+      </DialogBody>
+      <DialogFooter>
+        <DialogClose asChild>
+          <Button variant="outline">Cancel</Button>
+        </DialogClose>
+        <DialogClose asChild>
+          <Button>Confirm</Button>
+        </DialogClose>
+      </DialogFooter>
+    </DialogContent>
+  </Dialog>
+);
+
 export const RightSheet = () => (
   <Dialog>
     <DialogTrigger asChild>
diff --git a/tests/ui/dialog.test.tsx b/tests/ui/dialog.test.tsx
new file mode 100644
index 0000000..2d9efaa
--- /dev/null
+++ b/tests/ui/dialog.test.tsx
@@ -0,0 +1,151 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { describe, expect, test } from "bun:test";
+
+import {
+  Dialog,
+  DialogBody,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "../../src/ui/dialog.js";
+
+type Mounted = {
+  container: HTMLElement;
+  unmount: () => void;
+};
+
+function render(node: React.ReactElement): Mounted {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  let root!: Root;
+  act(() => {
+    root = createRoot(container);
+    root.render(node);
+  });
+  return {
+    container,
+    unmount: () => {
+      act(() => root.unmount());
+      container.remove();
+    },
+  };
+}
+
+function openDialog(side?: "center" | "left" | "right") {
+  return render(
+    <Dialog open>
+      <DialogContent side={side}>
+        <DialogHeader>
+          <DialogTitle>Title</DialogTitle>
+          <DialogDescription>Description</DialogDescription>
+        </DialogHeader>
+        <DialogBody>Body</DialogBody>
+        <DialogFooter>
+          <button type="button">Cancel</button>
+          <button type="button">Save</button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>,
+  );
+}
+
+describe("Dialog craft defaults", () => {
+  test("center content owns guttered width, max-height, and clipped overflow", () => {
+    const mounted = openDialog();
+    const content = document.querySelector('[data-slot="dialog-content"]');
+    expect(content).not.toBeNull();
+    expect(content?.getAttribute("data-side")).toBe("center");
+    const className = content?.getAttribute("class") ?? "";
+    expect(className).toContain("w-[min(calc(100vw-2rem),32rem)]");
+    expect(className).toContain("max-h-[min(90dvh,42rem)]");
+    expect(className).toContain("overflow-hidden");
+    expect(className).toContain("max-sm:w-[min(calc(100vw-1.25rem),32rem)]");
+    expect(className).toContain("max-sm:max-h-[min(92dvh,42rem)]");
+    // Side-sheet anchors must not leak onto the centre surface.
+    expect(className).not.toContain("inset-y-0");
+    expect(className).not.toContain("right-0");
+    expect(className).not.toContain("left-0");
+    mounted.unmount();
+  });
+
+  test("right sheet keeps full-height edge pinning without centre max-height", () => {
+    const mounted = openDialog("right");
+    const content = document.querySelector('[data-slot="dialog-content"]');
+    expect(content?.getAttribute("data-side")).toBe("right");
+    const className = content?.getAttribute("class") ?? "";
+    expect(className).toContain("inset-y-0");
+    expect(className).toContain("right-0");
+    expect(className).toContain("max-w-lg");
+    expect(className).not.toContain("max-h-[min(90dvh,42rem)]");
+    expect(className).not.toContain("overflow-hidden");
+    expect(className).not.toContain("-translate-x-1/2");
+    mounted.unmount();
+  });
+
+  test("left sheet mirrors right pinning on the opposite edge", () => {
+    const mounted = openDialog("left");
+    const content = document.querySelector('[data-slot="dialog-content"]');
+    expect(content?.getAttribute("data-side")).toBe("left");
+    const className = content?.getAttribute("class") ?? "";
+    expect(className).toContain("inset-y-0");
+    expect(className).toContain("left-0");
+    expect(className).toContain("border-r");
+    expect(className).not.toContain("right-0");
+    mounted.unmount();
+  });
+
+  test("header, body, footer, and title encode compact craft chrome", () => {
+    const mounted = openDialog();
+    const header = document.querySelector('[data-slot="dialog-header"]');
+    const body = document.querySelector('[data-slot="dialog-body"]');
+    const footer = document.querySelector('[data-slot="dialog-footer"]');
+    const title = document.querySelector('[data-slot="dialog-content"] h2');
+    const description = document.querySelector('[data-slot="dialog-content"] p');
+
+    expect(header?.className).toContain("shrink-0");
+    expect(header?.className).toContain("gap-1");
+    expect(header?.className).toContain("pr-8");
+
+    expect(body?.className).toContain("min-h-0");
+    expect(body?.className).toContain("flex-auto");
+    expect(body?.className).toContain("overflow-y-auto");
+    expect(body?.className).toContain("overscroll-contain");
+    expect(body?.className).toContain("[scrollbar-width:thin]");
+
+    expect(footer?.className).toContain("mt-auto");
+    expect(footer?.className).toContain("shrink-0");
+    expect(footer?.className).toContain("border-foreground/10");
+    expect(footer?.className).toContain("bg-foreground/[0.025]");
+    expect(footer?.className).toContain("pt-[0.85rem]");
+    expect(footer?.className).toContain("max-sm:flex-col");
+    expect(footer?.className).toContain("max-sm:[&>*]:w-full");
+
+    expect(title?.className).toContain("text-[0.95rem]");
+    expect(title?.className).toContain("font-[650]");
+    expect(title?.className).toContain("tracking-[-0.01em]");
+    expect(description?.className).toContain("text-[0.8125rem]");
+    expect(description?.className).toContain("leading-[1.4]");
+    mounted.unmount();
+  });
+
+  test("close control is a stable hit target with hover and focus chrome", () => {
+    const mounted = openDialog();
+    const close = document.querySelector('[data-slot="dialog-content"] > button[aria-label="Close"]');
+    expect(close).not.toBeNull();
+    const className = close?.getAttribute("class") ?? "";
+    expect(className).toContain("size-[1.8rem]");
+    expect(className).toContain("top-[0.85rem]");
+    expect(className).toContain("right-[0.85rem]");
+    expect(className).toContain("hover:bg-foreground/5");
+    expect(className).toContain("hover:text-foreground");
+    expect(className).toContain("focus-visible:outline-none");
+    expect(className).toContain("focus-visible:shadow-[0_0_0_3px_color-mix(in_srgb,var(--primary)_22%,transparent)]");
+    // Legacy opacity-only hover is gone — polish is color/background.
+    expect(className).not.toContain("opacity-70");
+    expect(className).not.toContain("hover:opacity-100");
+    mounted.unmount();
+  });
+});

From 5985ccd8746ecff66a11feffd14cc58028ad1625 Mon Sep 17 00:00:00 2001
From: Sawyer Cutler <sawyer@dirtroad.dev>
Date: Wed, 12 Aug 2026 16:48:14 -0700
Subject: [PATCH 5/7] Make dashboard stat tiles interactive

---
 src/ui/stat-grid.tsx                     |  54 +++++++++---
 stories/primitives/stat-grid.stories.tsx |   8 ++
 tests/ui/stat-grid.test.tsx              | 102 +++++++++++++++++++++++
 3 files changed, 154 insertions(+), 10 deletions(-)
 create mode 100644 tests/ui/stat-grid.test.tsx

diff --git a/src/ui/stat-grid.tsx b/src/ui/stat-grid.tsx
index 495a3b6..961f8d5 100644
--- a/src/ui/stat-grid.tsx
+++ b/src/ui/stat-grid.tsx
@@ -58,6 +58,11 @@ export type StatGridItemProps = {
   readonly sparklineValues?: readonly number[];
   /** Words for the built-in trend's shape; defaults to "{label} trend". */
   readonly sparklineLabel?: string;
+  /**
+   * When set, the tile is a real `<button>` and activates on click/Enter/Space.
+   * Static tiles stay a non-interactive `div` so they do not join the tab order.
+   */
+  readonly onClick?: () => void;
   readonly className?: string;
 };
 
@@ -66,6 +71,11 @@ export type StatGridItemProps = {
  * print. The value never carries direction by colour alone — `accent` and
  * `danger` are semantic tones the caller opts into, and the delta slot carries
  * its own words.
+ *
+ * Interaction is opt-in. With `onClick`, the shell is a `<button>` (not a div
+ * wearing `role="button"`) so keyboard activation is native. Shared layout
+ * classes stay identical; only the interactive shell adds hover/press
+ * affordance and the `text-left`/`w-full` button reset.
  */
 export function StatGridItem({
   label,
@@ -78,6 +88,7 @@ export function StatGridItem({
   sparkline,
   sparklineValues,
   sparklineLabel,
+  onClick,
   className,
 }: StatGridItemProps) {
   const sparklineNode =
@@ -86,15 +97,14 @@ export function StatGridItem({
       <Sparkline values={sparklineValues} summary={sparklineLabel ?? `${label} trend`} />
     ) : null);
 
-  return (
-    <div
-      data-slot="stat-grid-item"
-      className={cn(
-        "flex flex-col gap-1.5 rounded-[12px] border border-border bg-card",
-        emphasis === true ? "p-5 shadow-sm" : "p-4",
-        className,
-      )}
-    >
+  const shell = cn(
+    "flex flex-col gap-1.5 rounded-[12px] border border-border bg-card",
+    emphasis === true ? "p-5 shadow-sm" : "p-4",
+    className,
+  );
+
+  const body = (
+    <>
       <span className="text-[10px] font-semibold tracking-[0.12em] uppercase text-muted-foreground">{label}</span>
       <div className="flex items-baseline gap-2">
         <span
@@ -112,6 +122,30 @@ export function StatGridItem({
       {sub === undefined ? null : (
         <span className="text-[10px] tracking-[0.08em] uppercase text-muted-foreground">{sub}</span>
       )}
-    </div>
+    </>
+  );
+
+  if (onClick === undefined) {
+    return (
+      <div data-slot="stat-grid-item" className={shell}>
+        {body}
+      </div>
+    );
+  }
+
+  return (
+    <button
+      type="button"
+      data-slot="stat-grid-item"
+      onClick={onClick}
+      className={cn(
+        shell,
+        // text-left/w-full: button UA styles centre content and shrink-wrap.
+        // Hover/press only on the interactive shell so static tiles stay quiet.
+        "w-full cursor-pointer text-left transition-colors hover:border-primary-emphasis active:brightness-95",
+      )}
+    >
+      {body}
+    </button>
   );
 }
diff --git a/stories/primitives/stat-grid.stories.tsx b/stories/primitives/stat-grid.stories.tsx
index 532d930..4384d32 100644
--- a/stories/primitives/stat-grid.stories.tsx
+++ b/stories/primitives/stat-grid.stories.tsx
@@ -20,3 +20,11 @@ export const Headline = () => (
     <StatGridItem label="Approvals waiting" value="3" emphasis accent />
   </StatGrid>
 );
+
+export const Interactive = () => (
+  <StatGrid columns={3}>
+    <StatGridItem label="Purpose runs" value="128" onClick={() => {}} />
+    <StatGridItem label="Running now" value="4" onClick={() => {}} />
+    <StatGridItem label="Errored" value="2" danger onClick={() => {}} />
+  </StatGrid>
+);
diff --git a/tests/ui/stat-grid.test.tsx b/tests/ui/stat-grid.test.tsx
new file mode 100644
index 0000000..e571867
--- /dev/null
+++ b/tests/ui/stat-grid.test.tsx
@@ -0,0 +1,102 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { describe, expect, mock, test } from "bun:test";
+
+import { StatGrid, StatGridItem } from "../../src/ui/stat-grid.js";
+
+type Mounted = {
+  container: HTMLElement;
+  unmount: () => void;
+};
+
+function render(node: React.ReactElement): Mounted {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  let root!: Root;
+  act(() => {
+    root = createRoot(container);
+    root.render(node);
+  });
+  return {
+    container,
+    unmount: () => {
+      act(() => root.unmount());
+      container.remove();
+    },
+  };
+}
+
+const SHARED_LAYOUT = ["flex", "flex-col", "gap-1.5", "rounded-[12px]", "border", "border-border", "bg-card", "p-4"];
+
+describe("StatGridItem interaction", () => {
+  test("static tile is a non-interactive div with shared layout classes", () => {
+    const mounted = render(<StatGridItem label="Runs" value="42" />);
+    const tile = mounted.container.querySelector('[data-slot="stat-grid-item"]');
+    expect(tile).not.toBeNull();
+    expect(tile?.tagName).toBe("DIV");
+    expect(mounted.container.querySelector("button")).toBeNull();
+    const className = tile?.getAttribute("class") ?? "";
+    for (const token of SHARED_LAYOUT) {
+      expect(className).toContain(token);
+    }
+    expect(className).not.toContain("hover:border-primary-emphasis");
+    expect(className).not.toContain("cursor-pointer");
+    expect(tile?.textContent).toContain("Runs");
+    expect(tile?.textContent).toContain("42");
+    mounted.unmount();
+  });
+
+  test("interactive tile is a button with the same layout and click activation", () => {
+    const onClick = mock(() => {});
+    const mounted = render(<StatGridItem label="Runs" value="42" onClick={onClick} />);
+    const tile = mounted.container.querySelector('[data-slot="stat-grid-item"]');
+    expect(tile).not.toBeNull();
+    expect(tile?.tagName).toBe("BUTTON");
+    expect(tile?.getAttribute("type")).toBe("button");
+    const className = tile?.getAttribute("class") ?? "";
+    for (const token of SHARED_LAYOUT) {
+      expect(className).toContain(token);
+    }
+    expect(className).toContain("w-full");
+    expect(className).toContain("text-left");
+    expect(className).toContain("hover:border-primary-emphasis");
+    expect(className).toContain("cursor-pointer");
+    // Accessible name comes from the label + value content.
+    expect(tile?.textContent).toContain("Runs");
+    expect(tile?.textContent).toContain("42");
+
+    act(() => {
+      tile?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+    expect(onClick).toHaveBeenCalledTimes(1);
+    mounted.unmount();
+  });
+
+  test("emphasis padding is shared by static and interactive shells", () => {
+    const staticMount = render(<StatGridItem label="A" value="1" emphasis />);
+    const interactiveMount = render(<StatGridItem label="B" value="2" emphasis onClick={() => {}} />);
+    const staticClass = staticMount.container.querySelector('[data-slot="stat-grid-item"]')?.getAttribute("class") ?? "";
+    const interactiveClass =
+      interactiveMount.container.querySelector('[data-slot="stat-grid-item"]')?.getAttribute("class") ?? "";
+    expect(staticClass).toContain("p-5");
+    expect(staticClass).toContain("shadow-sm");
+    expect(interactiveClass).toContain("p-5");
+    expect(interactiveClass).toContain("shadow-sm");
+    staticMount.unmount();
+    interactiveMount.unmount();
+  });
+
+  test("StatGrid still lays out mixed static and interactive children", () => {
+    const mounted = render(
+      <StatGrid columns={2}>
+        <StatGridItem label="Static" value="1" />
+        <StatGridItem label="Clickable" value="2" onClick={() => {}} />
+      </StatGrid>,
+    );
+    const tiles = mounted.container.querySelectorAll('[data-slot="stat-grid-item"]');
+    expect(tiles.length).toBe(2);
+    expect(tiles[0]?.tagName).toBe("DIV");
+    expect(tiles[1]?.tagName).toBe("BUTTON");
+    mounted.unmount();
+  });
+});

From 2cb026c21e9539c41122c8a2bc5d3264f39cb135 Mon Sep 17 00:00:00 2001
From: Sawyer Cutler <sawyer@dirtroad.dev>
Date: Thu, 13 Aug 2026 17:28:03 -0700
Subject: [PATCH 6/7] Restyle the toast as a single bottom-center confirmation
 (#16)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The stock sonner surface slid up from the corner, stacked, and kept its
rounded card look. Mutation confirmations in the shell design are one
plain-text line that fades in over the bottom center, holds for 1.8s,
and fades out; a new confirmation dismisses the current one instead of
stacking. Each toast() call takes a fresh id — reusing one id inherits
the unmount sonner schedules while a dismissed toast is still animating
out, which would swallow a message fired in that window. The surface
introduces the theme's --border-strong and --shadow tokens: floating
chrome separates itself with the stronger border, not depth, so the
shadow ships as none and stays the single knob for elevation.
---
 src/theme.css                        |  31 ++++++++
 src/ui/toast.tsx                     |  51 +++++++++-----
 stories/primitives/toast.stories.tsx |  21 ++++++
 tests/ui/toast-edge.test.tsx         |  86 +++++++++++++++++++++++
 tests/ui/toast.test.tsx              | 101 +++++++++++++++++++++++++++
 5 files changed, 272 insertions(+), 18 deletions(-)
 create mode 100644 stories/primitives/toast.stories.tsx
 create mode 100644 tests/ui/toast-edge.test.tsx
 create mode 100644 tests/ui/toast.test.tsx

diff --git a/src/theme.css b/src/theme.css
index 4f6decf..d372fc4 100644
--- a/src/theme.css
+++ b/src/theme.css
@@ -58,9 +58,15 @@
   --destructive: #9e2b25;
   --destructive-foreground: #ffffff;
   --border: #dfe3e6;
+  --border-strong: #c3ccd2;
   --input: #8a8080;
   --ring: #9a5416;
 
+  /* The chrome's elevation. The design is flat — floating chrome separates
+     itself with --border-strong, not depth — so the token ships as `none`
+     and exists as the single knob if elevation ever returns. */
+  --shadow: none;
+
   /* Chart series, a fixed order rather than a pool — slot 1 is always the first
      series in the data. See lib/chart-palette.ts for why these steps and this
      ordering. The orange family is deliberately absent: orange is the reserved
@@ -98,8 +104,10 @@
   --destructive: #e6796f;
   --destructive-foreground: #000000;
   --border: #423a3b;
+  --border-strong: #5c5254;
   --input: #8a8080;
   --ring: #e98428;
+  --shadow: none;
 
   --chart-1: #5a95d8;
   --chart-2: #63a86a;
@@ -118,6 +126,7 @@
   --card: #f3efe8;
   --muted: #ebe6df;
   --border: #e2d9ce;
+  --border-strong: #c9bcab;
   --secondary: #d4cfc6;
   --secondary-foreground: #2b2627;
   --accent: #d4cfc6;
@@ -128,6 +137,7 @@
   --card: #322a26;
   --muted: #1c1614;
   --border: #4a3f3a;
+  --border-strong: #665750;
   --secondary: #3d342e;
   --secondary-foreground: #e4d5bc;
   --accent: #3d342e;
@@ -138,6 +148,7 @@
   --card: #eef2f6;
   --muted: #e8edf2;
   --border: #d5dde6;
+  --border-strong: #b6c3d0;
   --secondary: #b8c9d9;
   --secondary-foreground: #2b2627;
   --accent: #b8c9d9;
@@ -148,6 +159,7 @@
   --card: #1e242c;
   --muted: #14181e;
   --border: #3a424c;
+  --border-strong: #525c68;
   --secondary: #2a3d52;
   --secondary-foreground: #e4d5bc;
   --accent: #2a3d52;
@@ -176,8 +188,10 @@
   --color-destructive: var(--destructive);
   --color-destructive-foreground: var(--destructive-foreground);
   --color-border: var(--border);
+  --color-border-strong: var(--border-strong);
   --color-input: var(--input);
   --color-ring: var(--ring);
+  --shadow-surface: var(--shadow);
 
   /* The brand faces are named directly and are not bundled — the package ships
      no font files. A consumer that loads Red Hat Display / Space Mono gets the
@@ -393,6 +407,23 @@
   }
 }
 
+/* Toast motion: a pure 160ms fade, centered above the bottom edge — no
+   slide, no lift. Sonner enters and exits by transitioning translateY, so
+   the transform is pinned (!important, since sonner injects its stylesheet
+   at runtime after any linked sheet) and only opacity is left to move. The
+   durations stay normal-weight declarations so the reduced-motion override
+   below still collapses them. Ships by ui/toast. */
+[data-sonner-toaster] [data-sonner-toast].corbits-toast {
+  left: 50%;
+  transform: translateX(-50%) !important;
+  transition-property: opacity;
+  transition-duration: 160ms;
+  transition-timing-function: cubic-bezier(0.22, 1, 0.36, 1);
+}
+[data-sonner-toaster] [data-sonner-toast].corbits-toast[data-removed="true"] {
+  transition-timing-function: cubic-bezier(0.4, 0, 1, 1);
+}
+
 /* Motion is opt-out at the foundation, not per component: anything animated
    anywhere collapses to a single frame when the OS asks for reduced motion.
    Component families added later inherit this for free. */
diff --git a/src/ui/toast.tsx b/src/ui/toast.tsx
index a97f62d..0281b3c 100644
--- a/src/ui/toast.tsx
+++ b/src/ui/toast.tsx
@@ -1,28 +1,43 @@
-import { Toaster as Sonner, toast } from "sonner";
+import { Toaster as Sonner, toast as sonnerToast } from "sonner";
+
+const TOAST_DURATION_MS = 1800;
+
+let activeId: string | null = null;
+let sequence = 0;
 
 /**
- * Mount once at the app root. Sonner renders in a portal outside the Tailwind
- * tree, so the Corbits tokens are handed to it as inline CSS variables rather
- * than utility classes.
+ * Show a short plain-text confirmation. One toast at a time: a new call
+ * dismisses the current one and restarts the timer, so rapid mutations read
+ * as a single status line rather than a growing stack. Each call takes a
+ * fresh id — reusing one id would inherit the unmount sonner schedules while
+ * a dismissed toast is still animating out, swallowing the new message.
+ */
+export function toast(message: string) {
+  if (activeId !== null) sonnerToast.dismiss(activeId);
+  sequence += 1;
+  activeId = `corbits-toast-${sequence}`;
+  sonnerToast(message, { id: activeId, duration: TOAST_DURATION_MS });
+}
+
+/**
+ * Mount once at the app root. Sonner renders in a portal, so the toast is
+ * styled here (unstyled + utility classes) instead of inheriting from a
+ * surrounding component; its motion overrides live in theme.css under
+ * `.corbits-toast`.
  */
 export function Toaster(props: React.ComponentProps<typeof Sonner>) {
   return (
     <Sonner
-      className="font-sans"
-      style={
-        {
-          "--normal-bg": "var(--popover)",
-          "--normal-text": "var(--popover-foreground)",
-          "--normal-border": "var(--border)",
-          "--success-bg": "var(--success)",
-          "--success-text": "var(--success-foreground)",
-          "--error-bg": "var(--destructive)",
-          "--error-text": "var(--destructive-foreground)",
-        } as React.CSSProperties
-      }
+      position="bottom-center"
+      offset={{ bottom: "1.25rem" }}
+      mobileOffset={{ bottom: "1.25rem" }}
+      toastOptions={{
+        unstyled: true,
+        className:
+          "corbits-toast border border-border-strong bg-card shadow-surface " +
+          "px-[0.9rem] py-[0.55rem] font-sans text-[0.8rem] font-[550] text-foreground",
+      }}
       {...props}
     />
   );
 }
-
-export { toast };
diff --git a/stories/primitives/toast.stories.tsx b/stories/primitives/toast.stories.tsx
new file mode 100644
index 0000000..665890e
--- /dev/null
+++ b/stories/primitives/toast.stories.tsx
@@ -0,0 +1,21 @@
+import { Button } from "../../src/ui/button.js";
+import { toast, Toaster } from "../../src/ui/toast.js";
+
+export default { title: "Primitives / Toast" };
+
+/** Plain-text mutation confirmations. One toast at a time: firing another
+ * while one is visible replaces the message and restarts the timer. */
+export const Confirmations = () => (
+  <div className="flex flex-wrap items-center gap-2">
+    <Toaster />
+    <Button variant="outline" onClick={() => toast("Channel created")}>
+      Channel created
+    </Button>
+    <Button variant="outline" onClick={() => toast("Pinned Deploy notes")}>
+      Pinned
+    </Button>
+    <Button variant="outline" onClick={() => toast("Settings saved")}>
+      Settings saved
+    </Button>
+  </div>
+);
diff --git a/tests/ui/toast-edge.test.tsx b/tests/ui/toast-edge.test.tsx
new file mode 100644
index 0000000..3a5b428
--- /dev/null
+++ b/tests/ui/toast-edge.test.tsx
@@ -0,0 +1,86 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { toast, Toaster } from "../../src/ui/toast.js";
+
+type Mounted = {
+  container: HTMLElement;
+  unmount: () => void;
+};
+
+function render(node: React.ReactElement): Mounted {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  let root!: Root;
+  act(() => {
+    root = createRoot(container);
+    root.render(node);
+  });
+  return {
+    container,
+    unmount: () => {
+      act(() => root.unmount());
+      container.remove();
+    },
+  };
+}
+
+function visibleToasts() {
+  return document.body.querySelectorAll("[data-sonner-toast]");
+}
+
+async function wait(ms: number) {
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+  });
+}
+
+describe("toast replace-semantics edges", () => {
+  let mounted: Mounted | undefined;
+
+  afterEach(() => {
+    mounted?.unmount();
+    mounted = undefined;
+  });
+
+  test("replacing mid-display restarts the 1800ms timer", async () => {
+    mounted = render(<Toaster />);
+    act(() => toast("First"));
+    await wait(1200);
+    act(() => toast("Second"));
+    await wait(1200);
+    const shown = visibleToasts();
+    expect(shown.length).toBe(1);
+    expect(shown[0]?.textContent).toBe("Second");
+    expect(shown[0]?.getAttribute("data-removed")).toBe("false");
+    await wait(1300);
+    expect(visibleToasts().length).toBe(0);
+  });
+
+  test("firing during the previous toast's exit window still shows", async () => {
+    mounted = render(<Toaster />);
+    act(() => toast("First"));
+    await wait(1880);
+    const exiting = visibleToasts()[0];
+    expect(exiting?.getAttribute("data-removed")).toBe("true");
+    act(() => toast("Second"));
+    await wait(400);
+    const shown = visibleToasts();
+    expect(shown.length).toBe(1);
+    expect(shown[0]?.textContent).toBe("Second");
+    expect(shown[0]?.getAttribute("data-removed")).toBe("false");
+  });
+
+  test("firing after the previous toast fully unmounted shows again", async () => {
+    mounted = render(<Toaster />);
+    act(() => toast("First"));
+    await wait(2400);
+    expect(visibleToasts().length).toBe(0);
+    act(() => toast("Second"));
+    await wait(100);
+    const shown = visibleToasts();
+    expect(shown.length).toBe(1);
+    expect(shown[0]?.textContent).toBe("Second");
+  });
+});
diff --git a/tests/ui/toast.test.tsx b/tests/ui/toast.test.tsx
new file mode 100644
index 0000000..f987f23
--- /dev/null
+++ b/tests/ui/toast.test.tsx
@@ -0,0 +1,101 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { toast, Toaster } from "../../src/ui/toast.js";
+
+type Mounted = {
+  container: HTMLElement;
+  unmount: () => void;
+};
+
+function render(node: React.ReactElement): Mounted {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  let root!: Root;
+  act(() => {
+    root = createRoot(container);
+    root.render(node);
+  });
+  return {
+    container,
+    unmount: () => {
+      act(() => root.unmount());
+      container.remove();
+    },
+  };
+}
+
+function visibleToasts() {
+  return document.body.querySelectorAll("[data-sonner-toast]");
+}
+
+async function flush() {
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  });
+}
+
+describe("Toaster", () => {
+  let mounted: Mounted | undefined;
+
+  afterEach(() => {
+    mounted?.unmount();
+    mounted = undefined;
+  });
+
+  test("anchors the stack to the bottom center", async () => {
+    mounted = render(<Toaster />);
+    act(() => toast("Routine created"));
+    await flush();
+    const region = document.body.querySelector("[data-sonner-toaster]");
+    expect(region?.getAttribute("data-y-position")).toBe("bottom");
+    expect(region?.getAttribute("data-x-position")).toBe("center");
+  });
+
+  test("shows a plain-text confirmation", async () => {
+    mounted = render(<Toaster />);
+    act(() => toast("Channel created"));
+    await flush();
+    const shown = visibleToasts();
+    expect(shown.length).toBe(1);
+    expect(shown[0]?.textContent).toBe("Channel created");
+  });
+
+  test("styles the toast with the corbits class instead of sonner defaults", async () => {
+    mounted = render(<Toaster />);
+    act(() => toast("Settings saved"));
+    await flush();
+    const shown = visibleToasts()[0];
+    expect(shown?.classList.contains("corbits-toast")).toBe(true);
+    expect(shown?.getAttribute("data-styled")).toBe("false");
+  });
+
+  test("replaces the current toast instead of stacking a second one", async () => {
+    mounted = render(<Toaster />);
+    act(() => toast("Pinned Deploy notes"));
+    await flush();
+    act(() => toast("Unpinned Deploy notes"));
+    await flush();
+    const staying = document.body.querySelectorAll(
+      '[data-sonner-toast][data-removed="false"]',
+    );
+    expect(staying.length).toBe(1);
+    expect(staying[0]?.textContent).toBe("Unpinned Deploy notes");
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 300));
+    });
+    expect(visibleToasts().length).toBe(1);
+  });
+
+  test("dismisses on its own after the confirmation duration", async () => {
+    mounted = render(<Toaster />);
+    act(() => toast("Grant revoked"));
+    await flush();
+    expect(visibleToasts().length).toBe(1);
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 2400));
+    });
+    expect(visibleToasts().length).toBe(0);
+  });
+});

From fe973bae2eb92fc2dbdfd8aa07321793ab60bef1 Mon Sep 17 00:00:00 2001
From: Sawyer Cutler <sawyer@dirtroad.dev>
Date: Thu, 13 Aug 2026 17:29:52 -0700
Subject: [PATCH 7/7] =?UTF-8?q?CL-5971:=20Shell=20mock=20wants=20=E2=80=94?=
 =?UTF-8?q?=20component=20API=20additions=20(#17)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* RichEmptyState: optional actionSize to match denser host chrome

ActionControl hardcoded Button size="md". A stage empty-state embedded
under a top bar wants its actions at the same sm scale as the bar
around it, so actionSize is now threaded through, defaulting to md.

* FilterChip: give the unselected state a visible border

Unselected chips rendered as border-transparent bg-transparent — bare
text with no affordance that they are clickable. The unselected state
now carries the same border-border ring the selected state's card
treatment sits inside, so both states read as one pill family.

* CommandPalette: add inputAccessory and footer slots

No slot existed for a leading scope chip in the input row or a
keyboard-hint legend under the results. inputAccessory renders inside
the input row, ahead of the input; footer renders as a pinned strip
below the results (independent of the load-more control).

* SidebarRail: forward per-item data-* attributes and render id

SidebarRailItem carried no way to attach a DOM id or data-* attribute
to a specific item, so a consumer had no hook to target one rail
button (a tour, a spotlight). Extra item keys now spread onto the
rendered button, and the item's id renders as the button's DOM id.

* Add BlockCard and RiskBadge, lifted from Workbench's chat-ui

Generic versions of Workbench's generative-UI block frame and risk
callout: a zero-radius bordered card with a pulse-dot header, and a
tone-driven risk label. Adds --ok/--warn theme tokens (light/dark,
matching Workbench's app.css) since the risk tones need colours the
theme did not carry yet.

* SidebarItemRow: expose row radius and selected background as tokens

rounded-md and bg-primary/10 were hardcoded utilities a consumer's own
stylesheet could not out-cascade without matching specificity. The row
now reads --sidebar-row-radius and --sidebar-row-selected-bg (defined
in theme.css, defaulting to the previous values), so a consumer can
override them once on a scoping element instead of fighting the
utility.

* RiskBadge: low risk reads muted, not --ok green

The shell mock's only approve card renders its risk line in --warn
regardless of level — there's no green "all clear" treatment for risk.
Map low to --muted-foreground so only medium/high draw the eye; --ok
stays reserved for step/delivery "done" states.
---
 package.json                                  |  4 +
 scripts/contrast-test.mjs                     |  2 +
 src/index.ts                                  |  1 +
 src/theme.css                                 | 41 ++++++++++
 src/ui/block-card.tsx                         | 73 ++++++++++++++++++
 src/ui/command-palette.test.tsx               | 57 ++++++++++++++
 src/ui/command-palette.tsx                    | 53 ++++++++-----
 src/ui/filter-chip.tsx                        |  2 +-
 src/ui/rich-empty-state.tsx                   | 22 ++++--
 src/ui/sidebar-item-row.tsx                   |  6 +-
 src/ui/sidebar-rail.tsx                       | 14 +++-
 stories/chat/block-card.stories.tsx           | 23 ++++++
 .../primitives/command-palette.stories.tsx    | 47 ++++++++++++
 .../primitives/rich-empty-state.stories.tsx   | 11 +++
 .../sidebar-rail-and-panel.stories.tsx        | 32 +++++++-
 tests/ui/block-card.test.tsx                  | 74 +++++++++++++++++++
 tests/ui/filter-chip.test.tsx                 | 46 ++++++++++++
 tests/ui/rich-empty-state.test.tsx            | 52 +++++++++++++
 tests/ui/sidebar-item-row.test.tsx            | 48 ++++++++++++
 tests/ui/sidebar-rail.test.tsx                | 61 +++++++++++++++
 20 files changed, 639 insertions(+), 30 deletions(-)
 create mode 100644 src/ui/block-card.tsx
 create mode 100644 stories/chat/block-card.stories.tsx
 create mode 100644 stories/primitives/command-palette.stories.tsx
 create mode 100644 tests/ui/block-card.test.tsx
 create mode 100644 tests/ui/filter-chip.test.tsx
 create mode 100644 tests/ui/rich-empty-state.test.tsx
 create mode 100644 tests/ui/sidebar-item-row.test.tsx
 create mode 100644 tests/ui/sidebar-rail.test.tsx

diff --git a/package.json b/package.json
index 4b6f05f..200f128 100644
--- a/package.json
+++ b/package.json
@@ -279,6 +279,10 @@
       "types": "./dist/ui/bar-chart.d.ts",
       "default": "./dist/ui/bar-chart.js"
     },
+    "./ui/block-card": {
+      "types": "./dist/ui/block-card.d.ts",
+      "default": "./dist/ui/block-card.js"
+    },
     "./ui/boot-screen": {
       "types": "./dist/ui/boot-screen.d.ts",
       "default": "./dist/ui/boot-screen.js"
diff --git a/scripts/contrast-test.mjs b/scripts/contrast-test.mjs
index 81a0102..888429b 100644
--- a/scripts/contrast-test.mjs
+++ b/scripts/contrast-test.mjs
@@ -49,6 +49,8 @@ const REQUIRED = [
   "border",
   "input",
   "ring",
+  "ok",
+  "warn",
   // Five slots, matching CHART_SERIES_SLOTS in lib/chart-palette.ts.
   "chart-1",
   "chart-2",
diff --git a/src/index.ts b/src/index.ts
index abe5038..3152810 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -55,6 +55,7 @@ export * from "./ui/artifact-notice.js";
 export * from "./ui/avatar.js";
 export * from "./ui/badge.js";
 export * from "./ui/bar-chart.js";
+export * from "./ui/block-card.js";
 export * from "./ui/boot-screen.js";
 export * from "./ui/button.js";
 export * from "./ui/card.js";
diff --git a/src/theme.css b/src/theme.css
index d372fc4..4282228 100644
--- a/src/theme.css
+++ b/src/theme.css
@@ -62,6 +62,15 @@
   --input: #8a8080;
   --ring: #9a5416;
 
+  /* Status text, not a fill/foreground pair — used where a step or delivery
+     state needs to read as "good"/"caution" beyond what --success/--destructive
+     already carry (those are fills). --warn also colours a medium/high
+     RiskBadge; low risk stays --muted-foreground so only the levels worth
+     flagging draw the eye. Matches Workbench's app.css exactly, so a block
+     lifted from a consumer app keeps its colours. */
+  --ok: #37904a;
+  --warn: #b7791f;
+
   /* The chrome's elevation. The design is flat — floating chrome separates
      itself with --border-strong, not depth — so the token ships as `none`
      and exists as the single knob if elevation ever returns. */
@@ -109,6 +118,9 @@
   --ring: #e98428;
   --shadow: none;
 
+  --ok: #5cb573;
+  --warn: #d9a441;
+
   --chart-1: #5a95d8;
   --chart-2: #63a86a;
   --chart-3: #9fd8a8;
@@ -166,6 +178,19 @@
   --accent-foreground: #e4d5bc;
 }
 
+/* SidebarItemRow's own restyle points, deliberately outside `@theme inline`:
+   a Tailwind `bg-primary/10`/`rounded-md` pair is undefeatable without a
+   specificity war, since the utility and its override compile to the same
+   specificity and whichever rule is later in the sheet wins. A CSS variable
+   read at render time has none of that — a consumer sets it once on their own
+   root/scope and the row already reads it, no `!important` and no rebuild.
+   `color-mix` re-derives from `--primary` so both modes stay correct without
+   a `.dark` override of their own. */
+:root {
+  --sidebar-row-radius: var(--radius);
+  --sidebar-row-selected-bg: color-mix(in srgb, var(--primary) 10%, transparent);
+}
+
 @theme inline {
   --color-background: var(--background);
   --color-foreground: var(--foreground);
@@ -191,6 +216,8 @@
   --color-border-strong: var(--border-strong);
   --color-input: var(--input);
   --color-ring: var(--ring);
+  --color-ok: var(--ok);
+  --color-warn: var(--warn);
   --shadow-surface: var(--shadow);
 
   /* The brand faces are named directly and are not bundled — the package ships
@@ -307,6 +334,20 @@
   }
 }
 
+/* The block card's header dot: a plain opacity blink, distinct from the
+   status dot's outward-scaling ring — this one sits inline in a dense header
+   row where a scaling ring would collide with the title text next to it.
+   Used by ui/block-card. */
+@keyframes corbits-block-pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.35;
+  }
+}
+
 /* The boot screen's progress sweep. An indeterminate bar rather than a spinner:
    it says "still working" without implying a percentage nobody knows. Ships
    by ui/boot-screen. */
diff --git a/src/ui/block-card.tsx b/src/ui/block-card.tsx
new file mode 100644
index 0000000..b2062de
--- /dev/null
+++ b/src/ui/block-card.tsx
@@ -0,0 +1,73 @@
+import { TriangleAlert } from "lucide-react";
+import type { ReactNode } from "react";
+
+import { cn } from "../lib/utils.js";
+
+export type BlockCardProps = {
+  readonly title: string;
+  readonly children: ReactNode;
+  readonly className?: string;
+};
+
+/**
+ * The generative-UI block frame: a bordered, square-cornered card with a
+ * pulse-dot header. Zero radius is deliberate — it is what separates a
+ * generated block from the theme's otherwise-rounded surfaces, so a reader
+ * can tell "the agent made this" at a glance. Lifted out of a consumer app
+ * unchanged; see `RiskBadge` below for the tone it pairs with inside
+ * `children`.
+ */
+export function BlockCard({ title, children, className }: BlockCardProps) {
+  return (
+    <div data-slot="block-card" className={cn("overflow-hidden rounded-none border border-border bg-card", className)}>
+      <div
+        data-slot="block-card-header"
+        className="flex items-center gap-2 border-b border-border px-3.5 py-2.5 text-xs font-bold tracking-[0.02em] text-primary-emphasis"
+      >
+        <span
+          aria-hidden
+          className="size-1.5 shrink-0 rounded-none bg-current [animation:corbits-block-pulse_1.6s_ease_infinite]"
+        />
+        <span data-slot="block-card-title">{title}</span>
+      </div>
+      <div data-slot="block-card-body" className="p-4">
+        {children}
+      </div>
+    </div>
+  );
+}
+
+export type RiskLevel = "low" | "medium" | "high";
+
+export type RiskBadgeProps = {
+  readonly level: RiskLevel;
+  readonly label: string;
+  readonly note?: string;
+  readonly className?: string;
+};
+
+const RISK_TONE_CLASS: Record<RiskLevel, string> = {
+  low: "text-muted-foreground",
+  medium: "text-warn",
+  high: "text-destructive",
+};
+
+/**
+ * A risk callout for a block whose action carries consequence — approve this
+ * order cancellation, run this migration. `level` drives colour only; the
+ * `label` is what actually says what the risk is, so the badge is never a
+ * bare colour dot.
+ */
+export function RiskBadge({ level, label, note, className }: RiskBadgeProps) {
+  return (
+    <span
+      data-slot="risk-badge"
+      data-risk={level}
+      className={cn("inline-flex items-center gap-1.5 text-xs font-bold [&_svg]:size-3.5", RISK_TONE_CLASS[level], className)}
+    >
+      <TriangleAlert aria-hidden />
+      <span>{label}</span>
+      {note === undefined ? null : <span className="font-medium text-muted-foreground">{note}</span>}
+    </span>
+  );
+}
diff --git a/src/ui/command-palette.test.tsx b/src/ui/command-palette.test.tsx
index 5d733c1..74a0e3e 100644
--- a/src/ui/command-palette.test.tsx
+++ b/src/ui/command-palette.test.tsx
@@ -158,4 +158,61 @@ describe("CommandPalette", () => {
     expect(loadMoreCalls).toBe(1);
     root.unmount();
   });
+
+  test("inputAccessory renders leading the input, inside the input row", () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    act(() => {
+      root.render(
+        createElement(CommandPalette, {
+          open: true,
+          onOpenChange: () => {},
+          query: "",
+          onQueryChange: () => {},
+          groups: GROUPS,
+          onSelect: () => {},
+          inputAccessory: createElement("span", { "data-testid": "scope-chip" }, "This bench"),
+        }),
+      );
+    });
+    const accessory = document.body.querySelector("[data-slot='command-palette-input-accessory']");
+    expect(accessory).not.toBeNull();
+    expect(accessory?.textContent).toBe("This bench");
+    const input = document.body.querySelector("input");
+    expect(input).not.toBeNull();
+    const position = accessory!.compareDocumentPosition(input!);
+    expect(Boolean(position & Node.DOCUMENT_POSITION_FOLLOWING)).toBe(true);
+    root.unmount();
+  });
+
+  test("footer renders below the results as a legend strip", () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    act(() => {
+      root.render(
+        createElement(CommandPalette, {
+          open: true,
+          onOpenChange: () => {},
+          query: "",
+          onQueryChange: () => {},
+          groups: GROUPS,
+          onSelect: () => {},
+          footer: "↑↓ to navigate",
+        }),
+      );
+    });
+    const footer = document.body.querySelector("[data-slot='command-palette-footer']");
+    expect(footer).not.toBeNull();
+    expect(footer?.textContent).toBe("↑↓ to navigate");
+    root.unmount();
+  });
+
+  test("omits the accessory and footer slots when not provided", () => {
+    const { unmount } = mount();
+    expect(document.body.querySelector("[data-slot='command-palette-input-accessory']")).toBeNull();
+    expect(document.body.querySelector("[data-slot='command-palette-footer']")).toBeNull();
+    unmount();
+  });
 });
diff --git a/src/ui/command-palette.tsx b/src/ui/command-palette.tsx
index 66949c9..5f49434 100644
--- a/src/ui/command-palette.tsx
+++ b/src/ui/command-palette.tsx
@@ -39,6 +39,10 @@ export type CommandPaletteProps = {
   readonly hasMore?: boolean;
   readonly onLoadMore?: () => void;
   readonly placeholder?: string;
+  /** Leading content in the input row — a scope chip, a source badge. Sits before the input, inside the same row. */
+  readonly inputAccessory?: ReactNode;
+  /** A legend or hint strip pinned under the results, e.g. keyboard shortcut hints. */
+  readonly footer?: ReactNode;
   readonly className?: string;
 };
 
@@ -77,6 +81,8 @@ export function CommandPalette({
   hasMore = false,
   onLoadMore,
   placeholder = "Search or jump to…",
+  inputAccessory,
+  footer,
   className,
 }: CommandPaletteProps) {
   const inputRef = useRef<HTMLInputElement>(null);
@@ -113,23 +119,30 @@ export function CommandPalette({
         onKeyDown={navigation.onKeyDown}
       >
         <DialogTitle className="sr-only">Search</DialogTitle>
-        <input
-          ref={inputRef}
-          type="text"
-          role="combobox"
-          autoComplete="off"
-          spellCheck={false}
-          placeholder={placeholder}
-          aria-label="Search"
-          aria-expanded
-          aria-controls={`${baseId}-list`}
-          aria-activedescendant={navigation.activeId === undefined ? undefined : optionId(navigation.activeId)}
-          aria-autocomplete="list"
-          aria-busy={loading}
-          value={query}
-          onChange={(event) => onQueryChange(event.target.value)}
-          className="h-12 w-full shrink-0 border-b border-border bg-transparent px-4 text-sm outline-none placeholder:text-muted-foreground"
-        />
+        <div className="flex h-12 shrink-0 items-center gap-2 border-b border-border px-4">
+          {inputAccessory === undefined ? null : (
+            <div data-slot="command-palette-input-accessory" className="shrink-0">
+              {inputAccessory}
+            </div>
+          )}
+          <input
+            ref={inputRef}
+            type="text"
+            role="combobox"
+            autoComplete="off"
+            spellCheck={false}
+            placeholder={placeholder}
+            aria-label="Search"
+            aria-expanded
+            aria-controls={`${baseId}-list`}
+            aria-activedescendant={navigation.activeId === undefined ? undefined : optionId(navigation.activeId)}
+            aria-autocomplete="list"
+            aria-busy={loading}
+            value={query}
+            onChange={(event) => onQueryChange(event.target.value)}
+            className="h-full min-w-0 flex-1 bg-transparent text-sm outline-none placeholder:text-muted-foreground"
+          />
+        </div>
 
         <ul
           ref={listRef}
@@ -200,6 +213,12 @@ export function CommandPalette({
             </button>
           </div>
         ) : null}
+
+        {footer === undefined ? null : (
+          <div data-slot="command-palette-footer" className="border-t border-border px-3 py-2 text-xs text-muted-foreground">
+            {footer}
+          </div>
+        )}
       </DialogContent>
     </Dialog>
   );
diff --git a/src/ui/filter-chip.tsx b/src/ui/filter-chip.tsx
index ed0af4f..62029ce 100644
--- a/src/ui/filter-chip.tsx
+++ b/src/ui/filter-chip.tsx
@@ -27,7 +27,7 @@ export function FilterChip({ selected = false, onClick, children, count, classNa
         "inline-flex items-center gap-1 rounded-full border px-2.5 py-1 text-xs font-semibold transition-colors ease-out active:brightness-95",
         selected
           ? "border-border bg-card text-foreground shadow-sm"
-          : "border-transparent bg-transparent text-muted-foreground hover:bg-muted",
+          : "border-border bg-transparent text-muted-foreground hover:bg-muted hover:text-foreground",
         className,
       )}
     >
diff --git a/src/ui/rich-empty-state.tsx b/src/ui/rich-empty-state.tsx
index d822bc9..ce77252 100644
--- a/src/ui/rich-empty-state.tsx
+++ b/src/ui/rich-empty-state.tsx
@@ -1,7 +1,7 @@
 import type { ReactNode } from "react";
 
 import { cn } from "../lib/utils.js";
-import { Button } from "./button.js";
+import { Button, type ButtonProps } from "./button.js";
 
 export type RichEmptyStateAction = {
   readonly label: string;
@@ -22,20 +22,22 @@ export type RichEmptyStateProps = {
   readonly actions?: readonly RichEmptyStateAction[];
   /** Extra controls (e.g. a menu) below the primary actions. */
   readonly footer?: ReactNode;
+  /** Action button size. Defaults to `md`; `sm` matches a denser host chrome (e.g. a top bar). */
+  readonly actionSize?: ButtonProps["size"];
   readonly className?: string;
 };
 
-function ActionControl({ action }: { readonly action: RichEmptyStateAction }) {
+function ActionControl({ action, size }: { readonly action: RichEmptyStateAction; readonly size: ButtonProps["size"] }) {
   const variant = action.variant === "primary" ? "primary" : "secondary";
   if (action.href !== undefined) {
     return (
-      <Button asChild variant={variant} size="md">
+      <Button asChild variant={variant} size={size}>
         <a href={action.href}>{action.label}</a>
       </Button>
     );
   }
   return (
-    <Button type="button" variant={variant} size="md" onClick={action.onClick}>
+    <Button type="button" variant={variant} size={size} onClick={action.onClick}>
       {action.label}
     </Button>
   );
@@ -51,7 +53,15 @@ function ActionControl({ action }: { readonly action: RichEmptyStateAction }) {
  * icon stays decorative and hidden from assistive tech; the title carries the
  * meaning.
  */
-export function RichEmptyState({ icon, title, description, actions, footer, className }: RichEmptyStateProps) {
+export function RichEmptyState({
+  icon,
+  title,
+  description,
+  actions,
+  footer,
+  actionSize = "md",
+  className,
+}: RichEmptyStateProps) {
   return (
     <div
       data-slot="rich-empty-state"
@@ -70,7 +80,7 @@ export function RichEmptyState({ icon, title, description, actions, footer, clas
       {actions !== undefined && actions.length > 0 ? (
         <div className="mt-5 flex flex-wrap items-center justify-center gap-2">
           {actions.map((action) => (
-            <ActionControl key={action.label} action={action} />
+            <ActionControl key={action.label} action={action} size={actionSize} />
           ))}
         </div>
       ) : null}
diff --git a/src/ui/sidebar-item-row.tsx b/src/ui/sidebar-item-row.tsx
index 38f071a..9d8e165 100644
--- a/src/ui/sidebar-item-row.tsx
+++ b/src/ui/sidebar-item-row.tsx
@@ -77,8 +77,8 @@ export function SidebarItemRow({
     >
       <div
         className={cn(
-          "flex w-full items-center gap-2 rounded-md pr-1.5 text-sm transition-colors",
-          selected ? "bg-primary/10 text-primary-emphasis" : "text-foreground hover:bg-muted",
+          "flex w-full items-center gap-2 rounded-[var(--sidebar-row-radius)] pr-1.5 text-sm transition-colors",
+          selected ? "bg-[var(--sidebar-row-selected-bg)] text-primary-emphasis" : "text-foreground hover:bg-muted",
         )}
       >
         {/* The whole row's identity and selection live on this one button; the
@@ -88,7 +88,7 @@ export function SidebarItemRow({
           type="button"
           aria-current={selected ? "true" : undefined}
           onClick={onSelect}
-          className="flex min-w-0 flex-1 items-center gap-2 rounded-md py-1.5 pl-2 text-left active:brightness-95"
+          className="flex min-w-0 flex-1 items-center gap-2 rounded-[var(--sidebar-row-radius)] py-1.5 pl-2 text-left active:brightness-95"
         >
           {leading === undefined ? null : (
             <span className="grid size-5 shrink-0 place-items-center [&_svg]:size-4" aria-hidden>
diff --git a/src/ui/sidebar-rail.tsx b/src/ui/sidebar-rail.tsx
index 47276d9..a897b93 100644
--- a/src/ui/sidebar-rail.tsx
+++ b/src/ui/sidebar-rail.tsx
@@ -10,7 +10,17 @@ export type SidebarRailItem = {
   readonly icon: React.ReactNode;
   /** An unread dot or count. Rendered small and off to the icon's corner. */
   readonly badge?: React.ReactNode;
-};
+} & Omit<React.ComponentPropsWithoutRef<"button">, "id" | "type" | "onClick" | "children" | "className"> & {
+    /** Arbitrary `data-*` targeting attributes, e.g. `data-ctx-target` for a tour or spotlight. */
+    readonly [key: `data-${string}`]: string | number | boolean | undefined;
+  };
+
+/** Props this component manages itself — never spread onto the button, so an item can never clobber them by accident. */
+const OWN_ITEM_KEYS = new Set(["id", "label", "icon", "badge"]);
+
+function restItemProps(item: SidebarRailItem): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(item).filter(([key]) => !OWN_ITEM_KEYS.has(key)));
+}
 
 export type SidebarRailProps = {
   readonly items: readonly SidebarRailItem[];
@@ -69,7 +79,9 @@ export function SidebarRail({
           return (
             <li key={item.id} className="group relative w-full">
               <button
+                {...restItemProps(item)}
                 type="button"
+                id={item.id}
                 data-slot="sidebar-rail-item"
                 aria-current={active ? "page" : undefined}
                 aria-describedby={showLabels ? undefined : tooltipId}
diff --git a/stories/chat/block-card.stories.tsx b/stories/chat/block-card.stories.tsx
new file mode 100644
index 0000000..3695e30
--- /dev/null
+++ b/stories/chat/block-card.stories.tsx
@@ -0,0 +1,23 @@
+import { BlockCard, RiskBadge } from "../../src/ui/block-card.js";
+
+export default { title: "Chat / Block card" };
+
+export const Default = () => (
+  <BlockCard title="Cancel order #4821">
+    <p className="text-sm text-muted-foreground">Refunds the customer and releases the reserved inventory.</p>
+  </BlockCard>
+);
+
+export const RiskLevels = () => (
+  <div className="flex flex-col gap-4">
+    <BlockCard title="Send campaign">
+      <RiskBadge level="low" label="Low risk" note="Reversible within 5 minutes" />
+    </BlockCard>
+    <BlockCard title="Cancel order #4821">
+      <RiskBadge level="medium" label="Medium risk" note="Refund cannot be undone" />
+    </BlockCard>
+    <BlockCard title="Delete customer record">
+      <RiskBadge level="high" label="High risk" note="Permanent, no undo" />
+    </BlockCard>
+  </div>
+);
diff --git a/stories/primitives/command-palette.stories.tsx b/stories/primitives/command-palette.stories.tsx
new file mode 100644
index 0000000..f0f879b
--- /dev/null
+++ b/stories/primitives/command-palette.stories.tsx
@@ -0,0 +1,47 @@
+import { useState } from "react";
+
+import { CommandPalette, type CommandPaletteGroup } from "../../src/ui/command-palette.js";
+import { Badge } from "../../src/ui/badge.js";
+
+export default { title: "Primitives / Command palette" };
+
+const GROUPS: CommandPaletteGroup[] = [
+  {
+    id: "pages",
+    heading: "Pages",
+    items: [
+      { id: "page-1", title: "Settings" },
+      { id: "page-2", title: "Billing" },
+    ],
+  },
+  {
+    id: "entities",
+    heading: "Results",
+    items: [{ id: "entity-1", title: "Q3 Launch Plan", subtitle: "Artifact" }],
+  },
+];
+
+/** A scope chip leading the input, and a keyboard-hint legend pinned under the results. */
+export const WithAccessoryAndFooter = () => {
+  const [open, setOpen] = useState(true);
+  const [query, setQuery] = useState("");
+
+  return (
+    <CommandPalette
+      open={open}
+      onOpenChange={setOpen}
+      query={query}
+      onQueryChange={setQuery}
+      groups={GROUPS}
+      onSelect={() => {}}
+      inputAccessory={<Badge tone="accent">This bench</Badge>}
+      footer={
+        <div className="flex items-center gap-3">
+          <span>↑↓ to navigate</span>
+          <span>↵ to select</span>
+          <span>esc to close</span>
+        </div>
+      }
+    />
+  );
+};
diff --git a/stories/primitives/rich-empty-state.stories.tsx b/stories/primitives/rich-empty-state.stories.tsx
index 4423561..32106d8 100644
--- a/stories/primitives/rich-empty-state.stories.tsx
+++ b/stories/primitives/rich-empty-state.stories.tsx
@@ -22,3 +22,14 @@ export const MessageOnly = () => (
     description="Workflows you schedule will appear here with their next run time."
   />
 );
+
+/** `actionSize="sm"` matches a stage empty-state to a denser host chrome, e.g. a top bar. */
+export const CompactActions = () => (
+  <RichEmptyState
+    icon={<Inbox className="size-5" />}
+    title="No runs yet"
+    description="Trigger a run from the top bar to see it appear here."
+    actionSize="sm"
+    actions={[{ label: "Run now", variant: "primary" }]}
+  />
+);
diff --git a/stories/primitives/sidebar-rail-and-panel.stories.tsx b/stories/primitives/sidebar-rail-and-panel.stories.tsx
index 79472f7..68ee3bb 100644
--- a/stories/primitives/sidebar-rail-and-panel.stories.tsx
+++ b/stories/primitives/sidebar-rail-and-panel.stories.tsx
@@ -1,5 +1,5 @@
 import { Activity, Bell, Hash, Lock, MessagesSquare, Pin, Settings, User, Users, Workflow } from "lucide-react";
-import { useEffect, useState, type ReactNode } from "react";
+import { useEffect, useState, type CSSProperties, type ReactNode } from "react";
 
 import { useSidebarPanel } from "../../src/hooks/use-sidebar-panel.js";
 import { formatRelativeTime } from "../../src/lib/relative-time.js";
@@ -12,8 +12,11 @@ import { StatusDot } from "../../src/ui/status-dot.js";
 
 export default { title: "Primitives / Sidebar rail + panel" };
 
+// `data-ctx-target` on "channels" demonstrates a consumer attaching its own
+// targeting attribute (a tour, a spotlight) to a specific rail item — passed
+// straight through by SidebarRail to the rendered <button>.
 const PAGES: readonly SidebarRailItem[] = [
-  { id: "channels", label: "Channels", icon: <Hash /> },
+  { id: "channels", label: "Channels", icon: <Hash />, "data-ctx-target": "rail-channels" },
   { id: "routines", label: "Routines", icon: <Workflow /> },
   { id: "activity", label: "Activity", icon: <Activity />, badge: <StatusDot label="3 unread" tone="emphasis" size="xs" /> },
 ];
@@ -172,6 +175,31 @@ export const RoutinesActivity = () => {
   );
 };
 
+/**
+ * `--sidebar-row-radius`/`--sidebar-row-selected-bg` are the row's own restyle
+ * points — a consumer sets them once on a scoping element and every row under
+ * it reads the override, no specificity fight with the Tailwind utility the
+ * row ships with by default.
+ */
+export const CustomRowTokens = () => {
+  const [page] = useState("channels");
+  const { selectedId, select } = useSidebarPanel({ activePageId: page });
+
+  return (
+    <div style={{ "--sidebar-row-radius": "0px", "--sidebar-row-selected-bg": "color-mix(in srgb, var(--destructive) 12%, transparent)" } as CSSProperties}>
+      <TwoColumnShell page={page} onPageChange={() => undefined}>
+        <SidebarPanelHeader title="Channels" />
+        <SidebarPanelBody>
+          <SidebarPanelSection label="Channels">
+            <SidebarItemRow leading={<Hash className="text-muted-foreground" />} name="general" selected={selectedId === "general"} onSelect={() => select("general")} />
+            <SidebarItemRow leading={<Hash className="text-muted-foreground" />} name="eng" selected={selectedId === "eng"} onSelect={() => select("eng")} />
+          </SidebarPanelSection>
+        </SidebarPanelBody>
+      </TwoColumnShell>
+    </div>
+  );
+};
+
 export const PinsSection = () => {
   const [page] = useState("activity");
   const { selectedId, select } = useSidebarPanel({ activePageId: page });
diff --git a/tests/ui/block-card.test.tsx b/tests/ui/block-card.test.tsx
new file mode 100644
index 0000000..c48980d
--- /dev/null
+++ b/tests/ui/block-card.test.tsx
@@ -0,0 +1,74 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { describe, expect, test } from "bun:test";
+
+import { BlockCard, RiskBadge } from "../../src/ui/block-card.js";
+
+type Mounted = {
+  container: HTMLElement;
+  unmount: () => void;
+};
+
+function render(node: React.ReactElement): Mounted {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  let root!: Root;
+  act(() => {
+    root = createRoot(container);
+    root.render(node);
+  });
+  return {
+    container,
+    unmount: () => {
+      act(() => root.unmount());
+      container.remove();
+    },
+  };
+}
+
+describe("BlockCard", () => {
+  test("renders zero-radius bordered frame with title and body", () => {
+    const mounted = render(<BlockCard title="Cancel order">Body content</BlockCard>);
+    const card = mounted.container.querySelector("[data-slot='block-card']");
+    expect(card?.getAttribute("class") ?? "").toContain("rounded-none");
+    expect(mounted.container.querySelector("[data-slot='block-card-title']")?.textContent).toBe("Cancel order");
+    expect(mounted.container.textContent).toContain("Body content");
+    mounted.unmount();
+  });
+
+  test("header pulse dot is decorative and not announced twice", () => {
+    const mounted = render(<BlockCard title="Cancel order">Body</BlockCard>);
+    const header = mounted.container.querySelector("[data-slot='block-card-header']");
+    const dot = header?.firstElementChild;
+    expect(dot?.getAttribute("aria-hidden")).toBe("true");
+    mounted.unmount();
+  });
+});
+
+describe("RiskBadge", () => {
+  test.each([
+    ["low", "text-muted-foreground"],
+    ["medium", "text-warn"],
+    ["high", "text-destructive"],
+  ] as const)("level %s carries its own tone class", (level, toneClass) => {
+    const mounted = render(<RiskBadge level={level} label="Risk" />);
+    const badge = mounted.container.querySelector("[data-slot='risk-badge']");
+    expect(badge?.getAttribute("data-risk")).toBe(level);
+    expect(badge?.getAttribute("class") ?? "").toContain(toneClass);
+    mounted.unmount();
+  });
+
+  test("renders the label as real text, and an optional note alongside it", () => {
+    const mounted = render(<RiskBadge level="high" label="High risk" note="No undo" />);
+    expect(mounted.container.textContent).toContain("High risk");
+    expect(mounted.container.textContent).toContain("No undo");
+    mounted.unmount();
+  });
+
+  test("omits the note span when not provided", () => {
+    const mounted = render(<RiskBadge level="low" label="Low risk" />);
+    const badge = mounted.container.querySelector("[data-slot='risk-badge']");
+    expect(badge?.children.length).toBe(2);
+    mounted.unmount();
+  });
+});
diff --git a/tests/ui/filter-chip.test.tsx b/tests/ui/filter-chip.test.tsx
new file mode 100644
index 0000000..8469fcd
--- /dev/null
+++ b/tests/ui/filter-chip.test.tsx
@@ -0,0 +1,46 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { describe, expect, test } from "bun:test";
+
+import { FilterChip } from "../../src/ui/filter-chip.js";
+
+type Mounted = {
+  container: HTMLElement;
+  unmount: () => void;
+};
+
+function render(node: React.ReactElement): Mounted {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  let root!: Root;
+  act(() => {
+    root = createRoot(container);
+    root.render(node);
+  });
+  return {
+    container,
+    unmount: () => {
+      act(() => root.unmount());
+      container.remove();
+    },
+  };
+}
+
+describe("FilterChip unselected affordance", () => {
+  test("unselected renders a real border, not a bare-text button", () => {
+    const mounted = render(<FilterChip>Live</FilterChip>);
+    const button = mounted.container.querySelector("button");
+    const className = button?.getAttribute("class") ?? "";
+    expect(className).toContain("border-border");
+    expect(className).not.toContain("border-transparent");
+    mounted.unmount();
+  });
+
+  test("selected keeps its own card treatment", () => {
+    const mounted = render(<FilterChip selected>Live</FilterChip>);
+    const button = mounted.container.querySelector("button");
+    expect(button?.getAttribute("aria-pressed")).toBe("true");
+    expect(button?.getAttribute("class") ?? "").toContain("bg-card");
+    mounted.unmount();
+  });
+});
diff --git a/tests/ui/rich-empty-state.test.tsx b/tests/ui/rich-empty-state.test.tsx
new file mode 100644
index 0000000..d706607
--- /dev/null
+++ b/tests/ui/rich-empty-state.test.tsx
@@ -0,0 +1,52 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { describe, expect, test } from "bun:test";
+
+import { RichEmptyState } from "../../src/ui/rich-empty-state.js";
+
+type Mounted = {
+  container: HTMLElement;
+  unmount: () => void;
+};
+
+function render(node: React.ReactElement): Mounted {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  let root!: Root;
+  act(() => {
+    root = createRoot(container);
+    root.render(node);
+  });
+  return {
+    container,
+    unmount: () => {
+      act(() => root.unmount());
+      container.remove();
+    },
+  };
+}
+
+describe("RichEmptyState action size", () => {
+  test("defaults its action button to size md", () => {
+    const mounted = render(
+      <RichEmptyState title="Empty" description="Nothing here" actions={[{ label: "Go", variant: "primary" }]} />,
+    );
+    const button = mounted.container.querySelector("[data-slot='button']");
+    expect(button?.getAttribute("class") ?? "").toContain("h-9");
+    mounted.unmount();
+  });
+
+  test("actionSize='sm' shrinks the action button to match denser chrome", () => {
+    const mounted = render(
+      <RichEmptyState
+        title="Empty"
+        description="Nothing here"
+        actionSize="sm"
+        actions={[{ label: "Go", variant: "primary" }]}
+      />,
+    );
+    const button = mounted.container.querySelector("[data-slot='button']");
+    expect(button?.getAttribute("class") ?? "").toContain("h-8");
+    mounted.unmount();
+  });
+});
diff --git a/tests/ui/sidebar-item-row.test.tsx b/tests/ui/sidebar-item-row.test.tsx
new file mode 100644
index 0000000..8f51d08
--- /dev/null
+++ b/tests/ui/sidebar-item-row.test.tsx
@@ -0,0 +1,48 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { describe, expect, test } from "bun:test";
+
+import { SidebarItemRow } from "../../src/ui/sidebar-item-row.js";
+
+type Mounted = {
+  container: HTMLElement;
+  unmount: () => void;
+};
+
+function render(node: React.ReactElement): Mounted {
+  const container = document.createElement("ul");
+  document.body.appendChild(container);
+  let root!: Root;
+  act(() => {
+    root = createRoot(container);
+    root.render(node);
+  });
+  return {
+    container,
+    unmount: () => {
+      act(() => root.unmount());
+      container.remove();
+    },
+  };
+}
+
+describe("SidebarItemRow theming tokens", () => {
+  test("selected row's background reads the --sidebar-row-selected-bg token, not a hardcoded utility", () => {
+    const mounted = render(<SidebarItemRow name="general" selected />);
+    const row = mounted.container.querySelector("[data-slot='sidebar-item-row'] > div");
+    const className = row?.getAttribute("class") ?? "";
+    expect(className).toContain("bg-[var(--sidebar-row-selected-bg)]");
+    expect(className).not.toContain("bg-primary/10");
+    mounted.unmount();
+  });
+
+  test("row and its button read the --sidebar-row-radius token, not a hardcoded rounded-md", () => {
+    const mounted = render(<SidebarItemRow name="general" />);
+    const row = mounted.container.querySelector("[data-slot='sidebar-item-row'] > div");
+    const button = mounted.container.querySelector("button");
+    expect(row?.getAttribute("class") ?? "").toContain("rounded-[var(--sidebar-row-radius)]");
+    expect(button?.getAttribute("class") ?? "").toContain("rounded-[var(--sidebar-row-radius)]");
+    expect(row?.getAttribute("class") ?? "").not.toContain("rounded-md");
+    mounted.unmount();
+  });
+});
diff --git a/tests/ui/sidebar-rail.test.tsx b/tests/ui/sidebar-rail.test.tsx
new file mode 100644
index 0000000..b35aebe
--- /dev/null
+++ b/tests/ui/sidebar-rail.test.tsx
@@ -0,0 +1,61 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { describe, expect, test } from "bun:test";
+
+import { SidebarRail, type SidebarRailItem } from "../../src/ui/sidebar-rail.js";
+
+type Mounted = {
+  container: HTMLElement;
+  unmount: () => void;
+};
+
+function render(node: React.ReactElement): Mounted {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  let root!: Root;
+  act(() => {
+    root = createRoot(container);
+    root.render(node);
+  });
+  return {
+    container,
+    unmount: () => {
+      act(() => root.unmount());
+      container.remove();
+    },
+  };
+}
+
+describe("SidebarRail item rest props", () => {
+  test("forwards data-* attributes onto the rendered button", () => {
+    const items: readonly SidebarRailItem[] = [
+      { id: "channels", label: "Channels", icon: null, "data-ctx-target": "rail-channels" },
+      { id: "routines", label: "Routines", icon: null },
+    ];
+    const mounted = render(<SidebarRail items={items} activeId="channels" onSelect={() => {}} />);
+    const target = mounted.container.querySelector("[data-ctx-target='rail-channels']");
+    expect(target).not.toBeNull();
+    expect(target?.tagName).toBe("BUTTON");
+    mounted.unmount();
+  });
+
+  test("renders each item's id as the button's DOM id", () => {
+    const items: readonly SidebarRailItem[] = [{ id: "channels", label: "Channels", icon: null }];
+    const mounted = render(<SidebarRail items={items} activeId="channels" onSelect={() => {}} />);
+    const button = mounted.container.querySelector("button");
+    expect(button?.id).toBe("channels");
+    mounted.unmount();
+  });
+
+  test("a consumer's data-* attribute cannot clobber the component's own onClick handling", () => {
+    let selected = "";
+    const items: readonly SidebarRailItem[] = [{ id: "channels", label: "Channels", icon: null, "data-ctx-target": "rail-channels" }];
+    const mounted = render(<SidebarRail items={items} activeId="" onSelect={(id) => (selected = id)} />);
+    const button = mounted.container.querySelector("button") as HTMLButtonElement;
+    act(() => {
+      button.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+    expect(selected).toBe("channels");
+    mounted.unmount();
+  });
+});