@xemahq/ui-kernel 0.4.1 → 0.6.0

package/src/ui/design-tokens.ts

@@ -0,0 +1,346 @@
+/**
+ * Design Token System — Single source of truth for semantic styling.
+ *
+ * All components import from here. To reskin the app, edit this file + CSS variables.
+ * Uses Tailwind classes mapped to semantic states, priorities, and severities.
+ *
+ * COLOR PHILOSOPHY: Bold, vibrant primary colors (Microsoft-logo style).
+ * Red (#F25022), Green (#7FBA00), Blue (#00A4EF), Yellow (#FFB900) — strong, not pastel.
+ *
+ * DARK MODE: Uses opacity-based colors (e.g. bg-success/15) that adapt naturally.
+ * Text colors use dark: variants where needed for readable contrast.
+ */
+
+// ── Status Styles ──────────────────────────────────────────────────
+
+export interface StatusStyle {
+  badge: string;
+  dot: string;
+  text: string;
+  bg: string;
+  border: string;
+  icon: string;
+}
+
+// Reusable style fragments — keep the map below a flat enum-like lookup
+// rather than scattering bg-success/15 strings, so adding a new closed-set
+// status is a one-line entry.
+const SUCCESS_STYLE: StatusStyle = {
+  badge: 'bg-success/15 text-success dark:text-success border-success/30',
+  dot: 'bg-success',
+  text: 'text-success dark:text-success',
+  bg: 'bg-success/10',
+  border: 'border-success/30',
+  icon: 'text-success',
+};
+const WARNING_STYLE: StatusStyle = {
+  badge: 'bg-warning/15 text-warning dark:text-warning border-warning/30',
+  dot: 'bg-warning',
+  text: 'text-warning dark:text-warning',
+  bg: 'bg-warning/10',
+  border: 'border-warning/30',
+  icon: 'text-warning',
+};
+const INFO_STYLE: StatusStyle = {
+  badge: 'bg-info/15 text-info dark:text-info border-info/30',
+  dot: 'bg-info',
+  text: 'text-info dark:text-info',
+  bg: 'bg-info/10',
+  border: 'border-info/30',
+  icon: 'text-info',
+};
+const PRIMARY_STYLE: StatusStyle = {
+  badge: 'bg-primary/15 text-primary dark:text-primary border-primary/30',
+  dot: 'bg-primary',
+  text: 'text-primary dark:text-primary',
+  bg: 'bg-primary/10',
+  border: 'border-primary/30',
+  icon: 'text-primary',
+};
+const DESTRUCTIVE_STYLE: StatusStyle = {
+  badge: 'bg-destructive/15 text-destructive dark:text-destructive border-destructive/30',
+  dot: 'bg-destructive',
+  text: 'text-destructive dark:text-destructive',
+  bg: 'bg-destructive/10',
+  border: 'border-destructive/30',
+  icon: 'text-destructive',
+};
+const NEUTRAL_STYLE: StatusStyle = {
+  badge: 'bg-paper-elev text-ink-3 border-border',
+  dot: 'bg-muted-foreground/40',
+  text: 'text-ink-3',
+  bg: 'bg-muted/30',
+  border: 'border-border',
+  icon: 'text-ink-3',
+};
+
+// ── Tone Styles ────────────────────────────────────────────────────
+// Generic tonal palette used by `<ScopeBadge>` and any surface that
+// needs a closed-set chip without a status semantic. Status badges
+// continue to read from STATUS_STYLES (richer shape: badge + dot + …).
+
+export type Tone = 'neutral' | 'primary' | 'info' | 'success' | 'warning' | 'danger' | 'accent';
+
+export const TONE_STYLES: Record<Tone, string> = {
+  neutral: 'bg-paper-elev text-ink-3 border-border',
+  primary: 'bg-primary/10 text-primary border-primary/20',
+  info: 'bg-info/15 text-info dark:text-info border-info/20',
+  success: 'bg-success/15 text-success dark:text-success border-success/20',
+  warning: 'bg-warning/15 text-warning dark:text-warning border-warning/20',
+  danger: 'bg-destructive/15 text-destructive dark:text-destructive border-destructive/20',
+  accent: 'bg-amber-500/15 text-amber-700 dark:text-amber-400 border-amber-500/20',
+};
+
+export const STATUS_STYLES: Record<string, StatusStyle> = {
+  // ── Workflow run states (WorkflowRunStatus enum) ────────────────────
+  pending: INFO_STYLE,
+  running: WARNING_STYLE,
+  waiting_on_approval: WARNING_STYLE,
+  waiting_on_human: WARNING_STYLE,
+  succeeded: SUCCESS_STYLE,
+  failed: DESTRUCTIVE_STYLE,
+  cancelled: NEUTRAL_STYLE,
+  aborted_for_migration: NEUTRAL_STYLE,
+
+  // Legacy / generic synonyms — kept so older surfaces (project status,
+  // backlog "done") keep rendering correctly. Use the canonical run
+  // state above when emitting from new code.
+  completed: SUCCESS_STYLE,
+  stopped: WARNING_STYLE,
+  undone: PRIMARY_STYLE,
+  skipped: NEUTRAL_STYLE,
+
+  // ── Interactive session states (SessionStatus) ──────────────────────
+  creating: PRIMARY_STYLE,
+  provisioning: PRIMARY_STYLE,
+  active: SUCCESS_STYLE,
+  paused: WARNING_STYLE,
+  recovering: WARNING_STYLE,
+  completing: PRIMARY_STYLE,
+  archived: NEUTRAL_STYLE,
+
+  // ── Backlog / work ──────────────────────────────────────────────────
+  todo: NEUTRAL_STYLE,
+  in_progress: INFO_STYLE,
+  in_review: WARNING_STYLE,
+  done: SUCCESS_STYLE,
+  blocked: DESTRUCTIVE_STYLE,
+
+  // ── Design System Builder ───────────────────────────────────────────
+  open: INFO_STYLE,
+  exploring: WARNING_STYLE,
+  proposed: PRIMARY_STYLE,
+  accepted: SUCCESS_STYLE,
+  rejected: DESTRUCTIVE_STYLE,
+  merged: NEUTRAL_STYLE,
+
+  // ── SCM ─────────────────────────────────────────────────────────────
+  draft: NEUTRAL_STYLE,
+
+  // ── Gate ────────────────────────────────────────────────────────────
+  approved: SUCCESS_STYLE,
+  manual_review: WARNING_STYLE,
+};
+
+export function getStatusStyle(status: string): StatusStyle {
+  return STATUS_STYLES[status] ?? STATUS_STYLES.pending;
+}
+
+// ── Priority Styles ────────────────────────────────────────────────
+
+export interface PriorityStyle {
+  badge: string;
+  text: string;
+  bg: string;
+  border: string;
+  label: string;
+}
+
+export const PRIORITY_STYLES: Record<string, PriorityStyle> = {
+  p0: {
+    badge: 'bg-destructive text-white border-destructive',
+    text: 'text-destructive dark:text-destructive',
+    bg: 'bg-destructive/10',
+    border: 'border-destructive/30',
+    label: 'Critical',
+  },
+  p1: {
+    badge: 'bg-warning text-white border-warning',
+    text: 'text-warning dark:text-warning',
+    bg: 'bg-warning/10',
+    border: 'border-warning/30',
+    label: 'High',
+  },
+  p2: {
+    badge: 'bg-warning text-white border-warning',
+    text: 'text-warning dark:text-warning',
+    bg: 'bg-warning/10',
+    border: 'border-warning/30',
+    label: 'Medium',
+  },
+  p3: {
+    badge: 'bg-paper-elev text-ink-3 border-border',
+    text: 'text-ink-3',
+    bg: 'bg-muted/30',
+    border: 'border-border',
+    label: 'Low',
+  },
+};
+
+export function getPriorityStyle(priority: string): PriorityStyle {
+  return PRIORITY_STYLES[priority] ?? PRIORITY_STYLES.p3;
+}
+
+// ── Severity Styles ────────────────────────────────────────────────
+
+export interface SeverityStyle {
+  badge: string;
+  text: string;
+  bg: string;
+  border: string;
+}
+
+export const SEVERITY_STYLES: Record<string, SeverityStyle> = {
+  critical: {
+    badge: 'bg-destructive text-white border-destructive',
+    text: 'text-destructive dark:text-destructive',
+    bg: 'bg-destructive/10',
+    border: 'border-destructive/30',
+  },
+  error: {
+    badge: 'bg-destructive text-white border-destructive',
+    text: 'text-destructive dark:text-destructive',
+    bg: 'bg-destructive/10',
+    border: 'border-destructive/30',
+  },
+  major: {
+    badge: 'bg-warning text-white border-warning',
+    text: 'text-warning dark:text-warning',
+    bg: 'bg-warning/10',
+    border: 'border-warning/30',
+  },
+  warning: {
+    badge: 'bg-warning text-white border-warning',
+    text: 'text-warning dark:text-warning',
+    bg: 'bg-warning/10',
+    border: 'border-warning/30',
+  },
+  minor: {
+    badge: 'bg-info/15 text-info dark:text-info border-info/30',
+    text: 'text-info dark:text-info',
+    bg: 'bg-info/10',
+    border: 'border-info/30',
+  },
+  info: {
+    badge: 'bg-info/15 text-info dark:text-info border-info/30',
+    text: 'text-info dark:text-info',
+    bg: 'bg-info/10',
+    border: 'border-info/30',
+  },
+};
+
+export function getSeverityStyle(severity: string): SeverityStyle {
+  const s = severity.toLowerCase();
+  return SEVERITY_STYLES[s] ?? { badge: 'bg-paper-elev text-ink-3 border-border', text: 'text-ink-3', bg: 'bg-muted/30', border: 'border-border' };
+}
+
+// ── Type Styles (Backlog items) ────────────────────────────────────
+
+export const TYPE_STYLES: Record<string, { badge: string; text: string; border: string }> = {
+  epic: { badge: 'bg-primary/15 text-primary dark:text-primary border-primary/30', text: 'text-primary dark:text-primary', border: 'border-l-purple-600' },
+  story: { badge: 'bg-info/15 text-info dark:text-info border-info/30', text: 'text-info dark:text-info', border: 'border-l-blue-600' },
+  task: { badge: 'bg-success/15 text-success dark:text-success border-success/30', text: 'text-success dark:text-success', border: 'border-l-green-600' },
+  bug: { badge: 'bg-destructive/15 text-destructive dark:text-destructive border-destructive/30', text: 'text-destructive dark:text-destructive', border: 'border-l-red-600' },
+};
+
+// ── Card Styles ────────────────────────────────────────────────────
+
+export const CARD_STYLES = {
+  default: 'bg-card border border-border/50 rounded-xl shadow-[var(--shadow-2)]',
+  elevated: 'bg-card border border-border/40 rounded-xl shadow-[var(--shadow-8)]',
+  dark: 'bg-foreground text-background rounded-xl shadow-[var(--shadow-16)]',
+  accent: 'bg-primary/5 border border-primary/15 rounded-xl',
+  empty: 'border-2 border-dashed border-border/50 rounded-xl',
+} as const;
+
+// ── Section / Typography Styles ────────────────────────────────────
+
+export const SECTION_STYLES = {
+  pageTitle: 'text-lg sm:text-xl font-semibold tracking-tight text-ink',
+  sectionHeader: 'text-sm font-semibold text-ink',
+  cardLabel: 'text-[11px] font-semibold uppercase tracking-wider text-ink-3',
+  description: 'text-sm text-ink-3',
+  metricValue: 'text-xl sm:text-2xl font-semibold tabular-nums text-ink',
+  metricLabel: 'text-sm text-ink-3',
+} as const;
+
+// ── Importance Styles (Memory) ─────────────────────────────────────
+
+export const IMPORTANCE_STYLES: Record<number, { badge: string; label: string; star: string }> = {
+  1: { badge: 'bg-paper-elev text-ink-3 border-border', label: 'Low', star: 'text-ink-3' },
+  2: { badge: 'bg-info/15 text-info dark:text-info border-info/30', label: 'Normal', star: 'text-info' },
+  3: { badge: 'bg-warning/15 text-warning dark:text-warning border-warning/30', label: 'High', star: 'text-warning' },
+  4: { badge: 'bg-destructive/15 text-destructive dark:text-destructive border-destructive/30', label: 'Critical', star: 'text-destructive' },
+};
+
+// ── Risk Level Styles ──────────────────────────────────────────────
+
+export const RISK_LEVEL_STYLES: Record<string, { badge: string; text: string }> = {
+  low: { badge: 'bg-success/15 text-success dark:text-success border-success/30', text: 'text-success dark:text-success' },
+  medium: { badge: 'bg-warning/15 text-warning dark:text-warning border-warning/30', text: 'text-warning dark:text-warning' },
+  high: { badge: 'bg-warning/15 text-warning dark:text-warning border-warning/30', text: 'text-warning dark:text-warning' },
+  critical: { badge: 'bg-destructive/15 text-destructive dark:text-destructive border-destructive/30', text: 'text-destructive dark:text-destructive' },
+};
+
+export function getRiskLevelStyle(level: string): { badge: string; text: string } {
+  return RISK_LEVEL_STYLES[level] ?? RISK_LEVEL_STYLES.low;
+}
+
+// ── Agent Source Styles ────────────────────────────────────────────
+
+export const AGENT_SOURCE_STYLES: Record<string, { border: string; bg: string; icon: string; iconBg: string }> = {
+  dynamic: {
+    border: 'border-warning/30',
+    bg: 'bg-warning/5',
+    icon: 'text-warning',
+    iconBg: 'bg-warning/10',
+  },
+  predefined: {
+    border: 'border-border',
+    bg: 'bg-muted/20',
+    icon: 'text-primary',
+    iconBg: 'bg-primary/10',
+  },
+};
+
+// ── Kind Styles (Memory Graph Model) ─────────────────────────────────
+
+export const KIND_STYLES: Record<string, string> = {
+  LESSON: 'bg-info/15 text-info dark:text-info border-info/30',
+  PATTERN: 'bg-primary/15 text-primary dark:text-primary border-primary/30',
+  CORRECTION: 'bg-destructive/15 text-destructive dark:text-destructive border-destructive/30',
+  PREFERENCE: 'bg-success/15 text-success dark:text-success border-success/30',
+};
+
+// ── State Styles (Memory Graph Model) ────────────────────────────────
+
+export const STATE_STYLES: Record<string, string> = {
+  CANDIDATE: 'bg-paper-elev text-ink-3 border-border',
+  ACTIVE: 'bg-success/15 text-success dark:text-success border-success/30',
+  SUPERSEDED: 'bg-paper-elev text-ink-3 border-border line-through',
+  CONTRADICTED: 'bg-destructive/15 text-destructive dark:text-destructive border-destructive/30 line-through',
+  REVIEW_REQUIRED: 'bg-warning/15 text-warning dark:text-warning border-warning/30',
+  ARCHIVED: 'bg-paper-elev text-ink-3 border-border opacity-60',
+};
+
+// ── Origin Styles (Memory Graph Model) ───────────────────────────────
+
+export const ORIGIN_STYLES: Record<string, string> = {
+  GATE_REJECTION: 'bg-destructive/15 text-destructive dark:text-destructive border-destructive/30',
+  GATE_APPROVAL: 'bg-success/15 text-success dark:text-success border-success/30',
+  USER_CORRECTION: 'bg-warning/15 text-warning dark:text-warning border-warning/30',
+  MANUAL_OVERRIDE: 'bg-destructive/15 text-destructive dark:text-destructive border-destructive/30',
+  REVIEW_FINDING: 'bg-warning/15 text-warning dark:text-warning border-warning/30',
+  PATTERN_DETECTION: 'bg-primary/15 text-primary dark:text-primary border-primary/30',
+  USER_CREATED: 'bg-info/15 text-info dark:text-info border-info/30',
+};

package/src/ui/hooks/use-debounced-value.ts

@@ -0,0 +1,16 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Returns a debounced version of the provided value.
+ * Updates only after `delayMs` milliseconds of inactivity.
+ */
+export function useDebouncedValue<T>(value: T, delayMs = 300): T {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delayMs);
+    return () => clearTimeout(timer);
+  }, [value, delayMs]);
+
+  return debounced;
+}

package/src/ui/index.ts

@@ -12,6 +12,12 @@
 
 export { cn } from './cn';
 
+// ── design tokens (semantic styling SSOT) ──
+export * from './design-tokens';
+
+// ── hooks ──
+export { useDebouncedValue } from './hooks/use-debounced-value';
+
 // ── shadcn primitives ──
 export * from './primitives/button';
 export * from './primitives/badge';
@@ -38,9 +44,18 @@ export * from './primitives/radio-group';
 export * from './primitives/overflow-tabs';
 export * from './primitives/tag-multi-select';
 export * from './primitives/sheet';
+export * from './primitives/form-stepper';
+export * from './primitives/async-combobox';
 
 // ── Xema chrome ──
 export { default as ErrorCard, type ErrorMessageFormatter } from './chrome/ErrorCard';
+export { default as StatusBadge, type StatusBadgeProps, type StatusBadgeSize } from './chrome/status-badge';
+export { default as ScopeBadge, type ScopeBadgeProps } from './chrome/scope-badge';
+export {
+  default as ConfirmDeleteDialog,
+  type ConfirmDeleteDialogProps,
+} from './chrome/confirm-delete-dialog';
+export { default as PageShell } from './chrome/page-shell';
 export {
   default as EmptyState,
   type EmptyStateVariant,

package/src/ui/primitives/async-combobox.tsx

@@ -0,0 +1,178 @@
+import { useQuery } from '@tanstack/react-query';
+import { ChevronsUpDown, Loader2, Search } from 'lucide-react';
+import { useEffect, useRef, useState, type ReactNode } from 'react';
+
+import { cn } from '../cn';
+import { useDebouncedValue } from '../hooks/use-debounced-value';
+import { Button } from './button';
+import { Input } from './input';
+import { Popover, PopoverContent, PopoverTrigger } from './popover';
+
+export interface AsyncComboboxProps<T> {
+  /** Unique key prefix for query caching to avoid collisions between combobox instances. */
+  queryKeyPrefix?: string;
+  /** Currently selected item (null = nothing selected). */
+  value: T | null;
+  /** Text shown on the trigger when an item is selected. */
+  displayValue?: string;
+  /** Trigger button placeholder when nothing is selected. */
+  placeholder?: string;
+  /** Placeholder inside the search input. */
+  searchPlaceholder?: string;
+  /** Message shown when the search returns no results. */
+  emptyMessage?: string;
+  /** Async (or sync) function that returns items matching the query. */
+  onSearch: (query: string) => Promise<readonly T[]> | readonly T[];
+  /**
+   * Minimum characters before the search query is sent. Default is 0 — the
+   * picker fetches the full list as soon as it opens so users can browse
+   * without typing. Override to a higher number only when the underlying
+   * loader cannot handle an empty query (very large unbounded sets).
+   */
+  minSearchLength?: number;
+  /** Debounce delay in ms (default 300). */
+  debounceMs?: number;
+  /** Render a single result row. */
+  renderItem: (item: T) => ReactNode;
+  /** Unique key for each item. */
+  getItemKey: (item: T) => string;
+  /** Called when the user selects an item. */
+  onSelect: (item: T) => void;
+  /** Disable the combobox. */
+  disabled?: boolean;
+  /** Extra className for the trigger button. */
+  triggerClassName?: string;
+}
+
+/**
+ * Debounced async picker: a popover trigger + search input backed by a
+ * react-query'd loader. Host-framework-agnostic — the caller supplies the
+ * loader (`onSearch`) and row renderer, so it works against any data source.
+ *
+ * Requires `@tanstack/react-query` (an optional peer of the kernel) to be
+ * installed and a `QueryClientProvider` mounted above.
+ */
+export function AsyncCombobox<T>({
+  queryKeyPrefix = 'default',
+  value,
+  displayValue,
+  placeholder = 'Select…',
+  searchPlaceholder = 'Search…',
+  emptyMessage = 'No results found',
+  onSearch,
+  minSearchLength = 0,
+  debounceMs = 300,
+  renderItem,
+  getItemKey,
+  onSelect,
+  disabled,
+  triggerClassName,
+}: Readonly<AsyncComboboxProps<T>>) {
+  const [open, setOpen] = useState(false);
+  const [search, setSearch] = useState('');
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const debouncedSearch = useDebouncedValue(search, debounceMs);
+
+  const searchEnabled = open && debouncedSearch.length >= minSearchLength;
+
+  const { data: results = [], isLoading } = useQuery({
+    queryKey: ['async-combobox', queryKeyPrefix, debouncedSearch],
+    queryFn: () => onSearch(debouncedSearch),
+    enabled: searchEnabled,
+    staleTime: 30_000,
+  });
+
+  // Auto-focus the search input when the popover opens; clear search on close.
+  useEffect(() => {
+    if (open) {
+      const timer = setTimeout(() => inputRef.current?.focus(), 50);
+      return () => clearTimeout(timer);
+    }
+    setSearch('');
+    return undefined;
+  }, [open]);
+
+  const handleSelect = (item: T) => {
+    onSelect(item);
+    setOpen(false);
+  };
+
+  const showTypeToSearchHint =
+    !isLoading && minSearchLength > 0 && debouncedSearch.length < minSearchLength;
+  const showEmptyMessage = !isLoading && searchEnabled && results.length === 0;
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <Button
+          variant="outline"
+          role="combobox"
+          aria-expanded={open}
+          disabled={disabled}
+          className={cn(
+            'w-full justify-between font-normal',
+            !value && 'text-ink-3',
+            triggerClassName,
+          )}
+        >
+          <span className="truncate">
+            {value ? (displayValue ?? placeholder) : placeholder}
+          </span>
+          <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent
+        className="w-[--radix-popover-trigger-width] min-w-[18rem] p-0"
+        align="start"
+        onOpenAutoFocus={(e) => e.preventDefault()}
+      >
+        {/* Search input */}
+        <div className="relative border-b">
+          <Search className="absolute left-2.5 top-1/2 -translate-y-1/2 h-4 w-4 text-ink-3" />
+          <Input
+            ref={inputRef}
+            value={search}
+            onChange={(e) => setSearch(e.target.value)}
+            placeholder={searchPlaceholder}
+            className="h-9 text-body-1 pl-8 border-0 rounded-none focus-visible:ring-0 focus-visible:ring-offset-0"
+          />
+        </div>
+
+        {/* Results — native scroll, not Radix ScrollArea (which collapses
+            to content height when the parent uses max-h instead of h). */}
+        <div className="max-h-80 overflow-y-auto overscroll-contain">
+          <div className="p-1">
+            {isLoading && (
+              <div className="flex items-center justify-center py-4">
+                <Loader2 className="h-4 w-4 animate-spin text-ink-3" />
+              </div>
+            )}
+
+            {showTypeToSearchHint && (
+              <p className="text-body-1 text-ink-3 text-center py-4">
+                Type {minSearchLength}+ characters to search
+              </p>
+            )}
+
+            {showEmptyMessage && (
+              <p className="text-body-1 text-ink-3 text-center py-4">{emptyMessage}</p>
+            )}
+
+            {!isLoading &&
+              results.map((item) => (
+                <button
+                  key={getItemKey(item)}
+                  type="button"
+                  className="w-full text-left text-body-1 px-2 py-1.5 rounded hover:bg-paper-elev transition-colors flex items-center gap-2"
+                  onClick={() => handleSelect(item)}
+                >
+                  {renderItem(item)}
+                </button>
+              ))}
+          </div>
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}

package/src/ui/primitives/form-stepper.tsx

@@ -0,0 +1,109 @@
+import { Check } from 'lucide-react';
+
+import type { ReactNode } from 'react';
+
+import { cn } from '../cn';
+
+export enum FormStepStatus {
+  PENDING = 'pending',
+  ACTIVE = 'active',
+  DONE = 'done',
+}
+
+export interface FormStep {
+  readonly key: string;
+  readonly label: string;
+  readonly hint?: string;
+  readonly status: FormStepStatus;
+  readonly children: ReactNode;
+}
+
+interface FormStepperProps {
+  readonly steps: readonly FormStep[];
+}
+
+/**
+ * Vertical stepper for in-dialog multi-step forms — numbered badges with a
+ * connector rail. Every step's body is rendered inline (pending steps are
+ * dimmed and pointer-disabled). The dialog owns the submit button; this
+ * primitive renders structure only.
+ */
+export function FormStepper({ steps }: FormStepperProps) {
+  return (
+    <ol className="space-y-4">
+      {steps.map((step, index) => (
+        <FormStepperItem
+          key={step.key}
+          step={step}
+          stepNumber={index + 1}
+          isLast={index === steps.length - 1}
+        />
+      ))}
+    </ol>
+  );
+}
+
+interface FormStepperItemProps {
+  readonly step: FormStep;
+  readonly stepNumber: number;
+  readonly isLast: boolean;
+}
+
+function FormStepperItem({ step, stepNumber, isLast }: FormStepperItemProps) {
+  const isPending = step.status === FormStepStatus.PENDING;
+  const isDone = step.status === FormStepStatus.DONE;
+  const isActive = step.status === FormStepStatus.ACTIVE;
+
+  return (
+    <li className="relative flex gap-3">
+      {/* Connector rail — hugs the numbered badge column. Hidden on the last
+          item so the chain doesn't dangle past the final step. */}
+      {!isLast && (
+        <span
+          aria-hidden
+          className={cn(
+            'absolute left-3.5 top-8 bottom-0 w-px -translate-x-1/2',
+            isDone ? 'bg-primary/30' : 'bg-rule',
+          )}
+        />
+      )}
+
+      <span
+        className={cn(
+          'relative z-[1] mt-0.5 inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-full border text-caption font-semibold',
+          isDone && 'border-primary/40 bg-primary/15 text-primary',
+          isActive && 'border-primary bg-primary text-primary-foreground',
+          isPending && 'border-rule bg-paper-elev text-ink-3',
+        )}
+      >
+        {isDone ? <Check className="h-3.5 w-3.5" strokeWidth={2.5} /> : stepNumber}
+      </span>
+
+      <div
+        className={cn(
+          'flex-1 min-w-0 rounded-lg border bg-card p-4 transition-opacity',
+          isActive && 'border-primary/40 shadow-sm',
+          isDone && 'border-rule',
+          isPending && 'border-rule opacity-60',
+        )}
+      >
+        <div className="mb-3 space-y-0.5">
+          <p
+            className={cn(
+              'text-body-1 font-medium',
+              isPending ? 'text-ink-3' : 'text-foreground',
+            )}
+          >
+            {step.label}
+          </p>
+          {step.hint && <p className="text-caption text-ink-3">{step.hint}</p>}
+        </div>
+        {/* Keep pointer/keyboard focus out of pending steps without disabling
+            them globally — every input retains its native disabled semantics. */}
+        <div className={cn(isPending && 'pointer-events-none select-none')}>
+          {step.children}
+        </div>
+      </div>
+    </li>
+  );
+}