@utopia-studio-design/design-system-cli 0.8.1 → 0.8.3

package/data/ui-parts/blocks/analytics-dashboard/AnalyticsMetricBlocks.tsx

@@ -0,0 +1,87 @@
+import * as React from 'react'
+import { Badge } from '@utopia-studio-design/design-system/Badge'
+import type { ChartState } from '@utopia-studio-design/design-system/Charts'
+import './analytics-dashboard.css'
+
+export interface MetricDefinition {
+  change?: number
+  changeLabel?: string
+  format?: 'number' | 'percent' | 'currency'
+  id: string
+  label: string
+  value: number
+}
+
+export interface KPIGridProps extends React.HTMLAttributes<HTMLDivElement> {
+  currency?: string
+  density?: 'compact' | 'default' | 'comfortable'
+  locale?: string
+  metrics: MetricDefinition[]
+  state?: ChartState
+}
+
+export function KPIGrid({
+  className,
+  currency = 'USD',
+  density = 'default',
+  locale,
+  metrics,
+  state = metrics.length === 0 ? 'empty' : 'ready',
+  ...props
+}: KPIGridProps) {
+  const formatMetric = (metric: MetricDefinition) => {
+    if (metric.format === 'percent') {
+      return new Intl.NumberFormat(locale, { style: 'percent', maximumFractionDigits: 1 }).format(metric.value)
+    }
+    if (metric.format === 'currency') {
+      return new Intl.NumberFormat(locale, {
+        style: 'currency',
+        currency,
+        notation: 'compact',
+        maximumFractionDigits: 1,
+      }).format(metric.value)
+    }
+    return new Intl.NumberFormat(locale, { notation: 'compact', maximumFractionDigits: 1 }).format(metric.value)
+  }
+
+  return (
+    <section
+      aria-busy={state === 'loading'}
+      aria-label="Key performance indicators"
+      className={['ceramic-kpi-grid', className].filter(Boolean).join(' ')}
+      data-density={density}
+      data-state={state}
+      {...props}
+    >
+      {state === 'loading' ? (
+        <>
+          {[0, 1, 2].map((item) => <span aria-hidden="true" className="ceramic-kpi-skeleton" key={item} />)}
+          <span className="uds-visually-hidden" role="status">Loading metrics…</span>
+        </>
+      ) : null}
+      {state === 'empty' ? (
+        <div className="ceramic-kpi-state" role="status">
+          <strong>No metrics available</strong>
+          <span>Choose another period or data source.</span>
+        </div>
+      ) : null}
+      {state === 'error' ? (
+        <div className="ceramic-kpi-state" role="alert">
+          <strong>Metrics unavailable</strong>
+          <span>Reconnect the data source and try again.</span>
+        </div>
+      ) : null}
+      {state === 'ready' || state === 'partial' ? metrics.map((metric) => (
+        <article className="ceramic-kpi" key={metric.id}>
+          <span>{metric.label}</span>
+          <strong>{formatMetric(metric)}</strong>
+          {metric.change !== undefined ? (
+            <Badge variant="outline">
+              {metric.change > 0 ? '+' : ''}{metric.change.toFixed(1)}% {metric.changeLabel ?? 'vs previous'}
+            </Badge>
+          ) : <span className="ceramic-kpi-unavailable">No comparison</span>}
+        </article>
+      )) : null}
+    </section>
+  )
+}

package/data/ui-parts/blocks/analytics-dashboard/analytics-dashboard.css

@@ -0,0 +1,92 @@
+.ceramic-kpi-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 12rem), 1fr));
+  gap: var(--interaction-density-default);
+  min-inline-size: 0;
+}
+
+.ceramic-kpi-grid[data-density='compact'] {
+  gap: var(--interaction-density-compact);
+}
+
+.ceramic-kpi-grid[data-density='comfortable'] {
+  gap: var(--interaction-density-comfortable);
+}
+
+.ceramic-kpi {
+  display: grid;
+  align-content: start;
+  gap: var(--space-2);
+  min-inline-size: 0;
+  padding: var(--space-4);
+  border: var(--border-width-hairline) solid var(--border);
+  background: var(--surface);
+}
+
+.ceramic-kpi > span:first-child,
+.ceramic-kpi-unavailable {
+  color: var(--muted-foreground);
+  font-size: var(--font-size-small);
+}
+
+.ceramic-kpi > strong {
+  font-size: var(--font-size-marketing-h3);
+  font-weight: var(--font-weight-medium);
+  line-height: var(--line-height-tight);
+}
+
+.ceramic-kpi .uds-badge {
+  inline-size: fit-content;
+}
+
+.ceramic-kpi-state {
+  display: grid;
+  grid-column: 1 / -1;
+  justify-items: center;
+  gap: var(--space-2);
+  min-block-size: 10rem;
+  padding: var(--space-6);
+  border: var(--border-width-hairline) dashed var(--border);
+  color: var(--muted-foreground);
+  text-align: center;
+}
+
+.ceramic-kpi-state strong {
+  color: var(--foreground);
+}
+
+.ceramic-kpi-skeleton {
+  min-block-size: 9rem;
+  background: var(--surface-strong);
+}
+
+.ceramic-analytics-header {
+  display: flex;
+  align-items: end;
+  justify-content: space-between;
+  gap: var(--space-6);
+  padding-block: var(--space-6);
+  border-block-end: var(--border-width-hairline) solid var(--border);
+}
+
+.ceramic-analytics-header > div {
+  display: grid;
+  gap: var(--space-1);
+}
+
+.ceramic-analytics-header :is(h1, p) {
+  margin: 0;
+}
+
+.ceramic-analytics-header > div > span,
+.ceramic-analytics-header p {
+  color: var(--muted-foreground);
+  font-size: var(--font-size-small);
+}
+
+@media (max-width: 44rem) {
+  .ceramic-analytics-header {
+    align-items: stretch;
+    flex-direction: column;
+  }
+}

package/data/ui-parts/blocks/semantic-pattern-parts/AuthParts.tsx

@@ -0,0 +1,48 @@
+import { useId, useRef, useState, type ReactNode } from 'react'
+import { Button, TextInput } from '@utopia-studio-design/design-system'
+import { Eye, EyeOff } from 'lucide-react'
+import './auth-parts.css'
+
+/** Host-owned policy and labels: this meter is not a server password policy. */
+export function PasswordField({ label, value, onChange, showLabel, hideLabel, rules = [], error, hint }: {
+  label: string; value: string; onChange: (value: string) => void; showLabel: string; hideLabel: string;
+  rules?: { id: string; label: string; passed: boolean }[]; error?: string; hint?: string;
+}) {
+  const id = useId(), [shown, setShown] = useState(false)
+  return <div className="auth-part-field" data-slot="password-field">
+    <label htmlFor={id}>{label}</label>
+    <div className="auth-part-password"><TextInput id={id} type={shown ? 'text' : 'password'} value={value} onChange={e => onChange(e.target.value)} autoComplete="off" aria-invalid={Boolean(error)} aria-describedby={error || hint ? id + '-help' : undefined} /><Button type="button" variant="ghost" size="icon" onClick={() => setShown(v => !v)} aria-label={shown ? hideLabel : showLabel} aria-pressed={shown}>{shown ? <EyeOff aria-hidden="true" /> : <Eye aria-hidden="true" />}</Button></div>
+    {error || hint ? <p id={id + '-help'} data-error={Boolean(error)}>{error || hint}</p> : null}
+    {value && rules.length ? <ul className="auth-part-rules">{rules.map(rule => <li key={rule.id} data-passed={rule.passed}><span aria-hidden="true">{rule.passed ? '✓' : '○'}</span> {rule.label}</li>)}</ul> : null}
+  </div>
+}
+
+/** Six slots, paste, backspace and arrow movement; verification stays with host. */
+export function VerificationCode({ label, digitLabel, value, onChange, error, disabled = false }: {
+  label: string; digitLabel: (index: number) => string; value: string; onChange: (value: string) => void; error?: string; disabled?: boolean;
+}) {
+  const inputs = useRef<(HTMLInputElement | null)[]>([]), id = useId()
+  const update = (index: number, incoming: string) => {
+    const digits = incoming.replace(/\D/g, '').slice(0, 6 - index)
+    const slots = value.padEnd(6, ' ').split('')
+    slots.splice(index, Math.max(1, digits.length), ...(digits || ' ').split(''))
+    onChange(slots.slice(0, 6).join('').trimEnd())
+    if (digits) inputs.current[Math.min(index + digits.length, 5)]?.focus()
+  }
+  return <fieldset className="auth-part-code" data-slot="verification-code" aria-describedby={error ? id : undefined}>
+    <legend>{label}</legend><div dir="ltr">{Array.from({ length: 6 }, (_, index) => <TextInput key={index} ref={el => { inputs.current[index] = el }} aria-label={digitLabel(index + 1)} aria-invalid={Boolean(error)} aria-describedby={error ? id : undefined} inputMode="numeric" autoComplete={index === 0 ? 'one-time-code' : 'off'} value={value[index] ?? ''} disabled={disabled}
+      onChange={e => update(index, e.target.value)} onFocus={e => e.currentTarget.select()} onPaste={e => { e.preventDefault(); update(index, e.clipboardData.getData('text')) }}
+      onKeyDown={e => { if (e.key === 'ArrowLeft' || e.key === 'ArrowRight') { e.preventDefault(); inputs.current[Math.max(0, Math.min(5, index + (e.key === 'ArrowLeft' ? -1 : 1)))]?.focus() } else if (e.key === 'Backspace' && !value[index] && index) { e.preventDefault(); onChange(value.slice(0, index - 1)); inputs.current[index - 1]?.focus() } }} />)}</div>
+    {error ? <p id={id} role="alert">{error}</p> : null}
+  </fieldset>
+}
+
+export function ProviderButtons({ providers, onSelect, pending, label }: {
+  providers: { id: string; label: string }[]; onSelect: (id: string) => void; pending?: string; label: string;
+}) {
+  return <div className="auth-part-providers" data-slot="provider-sign-in" role="group" aria-label={label}>{providers.map(provider => <Button key={provider.id} type="button" variant="outline" disabled={Boolean(pending)} aria-busy={pending === provider.id} onClick={() => onSelect(provider.id)}>{provider.label}</Button>)}</div>
+}
+
+export function AuthFrame({ title, subtitle, footer, children, locale = 'en' }: { title: string; subtitle?: string; footer: string; children: ReactNode; locale?: string }) {
+  return <section className="ux-example ux-example--account" lang={locale} dir={locale === 'ar' ? 'rtl' : 'ltr'}><div className="ux-example__center"><div className="auth-part-frame"><header><h3>{title}</h3>{subtitle ? <p>{subtitle}</p> : null}</header>{children}</div></div><footer>{footer}</footer></section>
+}

package/data/ui-parts/blocks/semantic-pattern-parts/ChoiceCards.tsx

@@ -0,0 +1,7 @@
+import { Button } from '@utopia-studio-design/design-system'
+import type { PatternOption } from './types'
+import './pattern-parts.css'
+
+export function ChoiceCards({ label, options, value, onChange }: { label: string; options: PatternOption[]; value: string; onChange: (id: string) => void }) {
+  return <fieldset className="pattern-parts pattern-choices" data-slot="pattern-choices"><legend>{label}</legend><div>{options.map(option => <Button key={option.id} type="button" variant="outline" aria-pressed={value === option.id} onClick={() => onChange(option.id)}><strong>{option.label}</strong>{option.description ? <span>{option.description}</span> : null}</Button>)}</div></fieldset>
+}

package/data/ui-parts/blocks/semantic-pattern-parts/ListFilters.tsx

@@ -0,0 +1,9 @@
+import { useId } from 'react'
+import { Button, TextInput, NativeSelect } from '@utopia-studio-design/design-system'
+import type { PatternOption } from './types'
+import './pattern-parts.css'
+
+export function ListFilters({ label, query, onQueryChange, queryLabel, status, onStatusChange, statusLabel, options, resetLabel }: { label: string; query: string; onQueryChange: (query: string) => void; queryLabel: string; status: string; onStatusChange: (status: string) => void; statusLabel: string; options: PatternOption[]; resetLabel: string }) {
+  const id = useId()
+  return <section className="pattern-parts pattern-filters" data-slot="pattern-filters" aria-label={label}><div><label htmlFor={`${id}-query`}>{queryLabel}</label><TextInput id={`${id}-query`} type="search" value={query} onChange={event => onQueryChange(event.target.value)} /></div><div><label htmlFor={`${id}-status`}>{statusLabel}</label><NativeSelect id={`${id}-status`} value={status} onChange={event => onStatusChange(event.target.value)}>{options.map(option => <option value={option.id} key={option.id}>{option.label}</option>)}</NativeSelect></div><Button type="button" variant="outline" onClick={() => { onQueryChange(''); onStatusChange(options[0]?.id ?? '') }}>{resetLabel}</Button></section>
+}

package/data/ui-parts/blocks/semantic-pattern-parts/OutcomeNotice.tsx

@@ -0,0 +1,7 @@
+import type { ReactNode } from 'react'
+import { Button } from '@utopia-studio-design/design-system'
+import './pattern-parts.css'
+
+export function OutcomeNotice({ title, children, actionLabel, onAction, tone = 'info' }: { title: string; children: ReactNode; actionLabel: string; onAction: () => void; tone?: 'info' | 'success' | 'warning' }) {
+  return <section className="pattern-parts pattern-result" data-slot="pattern-result" data-tone={tone}><div role="status"><strong>{title}</strong><p>{children}</p></div><Button type="button" variant="outline" onClick={onAction}>{actionLabel}</Button></section>
+}

package/data/ui-parts/blocks/semantic-pattern-parts/ProductParts.tsx

@@ -0,0 +1,38 @@
+import { Button, NativeSelect } from '@utopia-studio-design/design-system'
+import './product-parts.css'
+
+/** Rows represent destinations; the host supplies navigation, not this part. */
+export function ActivityList({ items, emptyLabel, unreadLabel, onOpen }: {
+  items: { id: string; title: string; body: string; time: string; unread?: boolean }[];
+  emptyLabel: string; unreadLabel: string; onOpen: (id: string) => void;
+}) {
+  if (!items.length) return <p className="product-card" role="status">{emptyLabel}</p>
+  return <ul className="product-list" data-slot="activity-list">{items.map(item => <li key={item.id}>
+    <button className="product-row" data-slot="activity-row" data-unread={Boolean(item.unread)} onClick={() => onOpen(item.id)} type="button">
+      <span className="product-row__content"><strong>{item.title}</strong><span>{item.body}</span></span>
+      <span className="product-row__meta"><span>{item.time}</span>{item.unread ? <strong>{unreadLabel}</strong> : null}</span>
+    </button>
+  </li>)}</ul>
+}
+
+/** Selected channels and mandatory-delivery policy belong to the host. */
+export function ChannelPreferences({ items, options, requiredLabel, onChange }: {
+  items: { id: string; title: string; description: string; channel: string; disallowed?: string[] }[];
+  options: { id: string; label: string }[]; requiredLabel: string; onChange: (id: string, channel: string) => void;
+}) {
+  return <div className="product-list" data-slot="channel-preferences">{items.map(item => <div className="product-setting" key={item.id}>
+    <div><strong>{item.title}</strong><p>{item.description}</p>{item.disallowed?.length ? <small>{requiredLabel}</small> : null}</div>
+    <NativeSelect aria-label={item.title} value={item.channel} onChange={e => onChange(item.id, e.target.value)}>{options.map(option => <option key={option.id} value={option.id} disabled={item.disallowed?.includes(option.id)}>{option.label}</option>)}</NativeSelect>
+  </div>)}</div>
+}
+
+export function DirectoryCards({ items, emptyLabel, profileLabel, actionLabel, onProfile, onAction }: {
+  items: { id: string; name: string; role: string; organization: string; languages: string; expertise: string; availability: string; stats: string }[];
+  emptyLabel: string; profileLabel: string; actionLabel: string; onProfile: (id: string) => void; onAction: (id: string) => void;
+}) {
+  if (!items.length) return <p className="product-card" role="status">{emptyLabel}</p>
+  return <ul className="product-grid" data-slot="directory-cards">{items.map(item => <li className="product-card" data-slot="directory-card" key={item.id}>
+    <header><strong>{item.name}</strong><p>{item.role}</p></header><span>{item.availability}</span><p>{item.stats}</p><p>{item.organization} · {item.languages}</p><p>{item.expertise}</p>
+    <div className="product-actions"><Button onClick={() => onAction(item.id)}>{actionLabel}</Button><Button variant="outline" onClick={() => onProfile(item.id)}>{profileLabel}</Button></div>
+  </li>)}</ul>
+}

package/data/ui-parts/blocks/semantic-pattern-parts/ProgressSteps.tsx

@@ -0,0 +1,6 @@
+import { Button } from '@utopia-studio-design/design-system'
+import './pattern-parts.css'
+
+export function ProgressSteps({ label, steps, onSelect }: { label: string; steps: { id: string; label: string; status: 'done' | 'current' | 'locked'; statusLabel: string }[]; onSelect: (id: string) => void }) {
+  return <nav className="pattern-parts pattern-steps" data-slot="pattern-steps" aria-label={label}><ol>{steps.map((step, index) => <li key={step.id}><Button variant={step.status === 'current' ? 'default' : 'outline'} disabled={step.status === 'locked'} aria-current={step.status === 'current' ? 'step' : undefined} onClick={() => onSelect(step.id)}><span aria-hidden="true">{step.status === 'done' ? '✓' : index + 1}</span><strong>{step.label}</strong><span>{step.statusLabel}</span></Button></li>)}</ol></nav>
+}

package/data/ui-parts/blocks/semantic-pattern-parts/ReviewList.tsx

@@ -0,0 +1,7 @@
+import { Button, Badge, DataTable, DataTableShell, DataTableHeader, DataTableBody, DataTableRow, DataTableHead, DataTableCell } from '@utopia-studio-design/design-system'
+import type { ReviewItem } from './types'
+import './pattern-parts.css'
+
+export function ReviewList({ label, rows, columns, state = 'ready', message, retryLabel, onRetry, onReview, reviewLabel }: { label: string; rows: ReviewItem[]; columns: [string, string, string, string]; state?: 'loading' | 'error' | 'ready'; message: string; retryLabel: string; onRetry: () => void; onReview: (id: string) => void; reviewLabel: (row: ReviewItem) => string }) {
+  return <section className="pattern-parts pattern-review" data-slot="pattern-review" aria-label={label} aria-busy={state === 'loading'}>{state !== 'ready' ? <div className="pattern-result"><p role={state === 'error' ? 'alert' : 'status'}>{message}</p>{state === 'error' ? <Button variant="outline" onClick={onRetry}>{retryLabel}</Button> : null}</div> : <DataTableShell><DataTable aria-label={label}><DataTableHeader><DataTableRow>{columns.map(column => <DataTableHead key={column}>{column}</DataTableHead>)}</DataTableRow></DataTableHeader><DataTableBody>{rows.map(row => <DataTableRow key={row.id}><DataTableCell><strong>{row.title}</strong>{row.description ? <p>{row.description}</p> : null}</DataTableCell><DataTableCell><Badge variant="secondary">{row.status}</Badge></DataTableCell><DataTableCell>{row.assignee}</DataTableCell><DataTableCell><Button variant="outline" size="sm" onClick={() => onReview(row.id)}>{reviewLabel(row)}</Button></DataTableCell></DataTableRow>)}{!rows.length ? <DataTableRow><DataTableCell colSpan={4}><p role="status">{message}</p></DataTableCell></DataTableRow> : null}</DataTableBody></DataTable></DataTableShell>}</section>
+}

package/data/ui-parts/blocks/semantic-pattern-parts/ValidatedField.tsx

@@ -0,0 +1,8 @@
+import { useId } from 'react'
+import { TextInput } from '@utopia-studio-design/design-system'
+import './pattern-parts.css'
+
+export function ValidatedField({ label, value, onChange, hint, error, type = 'text', required = false }: { label: string; value: string; onChange: (value: string) => void; hint?: string; error?: string; type?: 'text' | 'email'; required?: boolean }) {
+  const id = useId()
+  return <div className="pattern-parts pattern-field" data-slot="pattern-field"><label htmlFor={id}>{label}</label><TextInput id={id} type={type} value={value} onChange={event => onChange(event.target.value)} required={required} aria-invalid={Boolean(error)} aria-describedby={error || hint ? `${id}-help` : undefined} />{error || hint ? <p id={`${id}-help`} data-error={Boolean(error)}>{error || hint}</p> : null}</div>
+}

package/data/ui-parts/blocks/semantic-pattern-parts/WorkflowParts.tsx

@@ -0,0 +1,339 @@
+import { useId } from "react";
+import {
+  Button,
+  TextInput,
+  TextArea,
+  NativeSelect,
+} from "@utopia-studio-design/design-system";
+import "./workflow-parts.css";
+import "./product-parts.css";
+
+export type WorkflowField = {
+  id: string;
+  label: string;
+  type?:
+    | "text"
+    | "email"
+    | "date"
+    | "time"
+    | "number"
+    | "url"
+    | "textarea"
+    | "select"
+    | "multi-select"
+    | "check"
+    | "file";
+  options?: string[];
+  required?: boolean;
+  minLength?: number;
+  min?: number;
+  max?: number;
+  accept?: string;
+  hint?: string;
+};
+
+/** Pure field rendering. Validation, uploaded file handling and persistence belong to the host. */
+export function WorkflowFields({
+  fields,
+  values,
+  errors = {},
+  onChange,
+  onFile,
+}: {
+  fields: WorkflowField[];
+  values: Record<string, string>;
+  errors?: Record<string, string>;
+  onChange: (id: string, value: string) => void;
+  onFile?: (id: string, file: File | undefined) => void;
+}) {
+  const prefix = useId();
+  return (
+    <div className="workflow-fields" data-slot="workflow-fields">
+      {fields.map((field) => {
+        const id = `${prefix}-${field.id}`,
+          error = errors[field.id];
+        const shared = {
+          id,
+          required: field.required,
+          "aria-invalid": Boolean(error),
+          "aria-describedby": `${id}-help`,
+          value: values[field.id] ?? "",
+          onChange: (
+            e: React.ChangeEvent<
+              HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement
+            >
+          ) => onChange(field.id, e.target.value),
+        };
+        if (field.type === 'multi-select') {
+          const selected = (values[field.id] ?? '').split('\n').filter(Boolean)
+          return <fieldset className="product-card" data-slot="workflow-multi-select" key={field.id} aria-describedby={`${id}-help`} aria-invalid={Boolean(error)}>
+            <legend>{field.label}{field.required ? ' *' : ''}</legend>
+            <div className="workflow-fields">{field.options?.map(option => <label className="ux-example__check" key={option}><input type="checkbox" checked={selected.includes(option)} onChange={e => onChange(field.id, (e.target.checked ? [...selected, option] : selected.filter(v=>v!==option)).join('\n'))} />{option}</label>)}</div>
+            <small id={`${id}-help`} data-error={Boolean(error)}>{error || field.hint}</small>
+          </fieldset>
+        }
+        return (
+          <div className="workflow-field" key={field.id}>
+            <label htmlFor={id}>
+              {field.label}
+              {field.required ? " *" : ""}
+            </label>
+            {field.type === "check" ? (
+              <input
+                id={id}
+                type="checkbox"
+                checked={values[field.id] === "true"}
+                required={field.required}
+                aria-invalid={Boolean(error)}
+                aria-describedby={`${id}-help`}
+                onChange={(e) => onChange(field.id, String(e.target.checked))}
+              />
+            ) : field.type === "file" ? (
+              <input
+                id={id}
+                type="file"
+                accept={field.accept}
+                aria-invalid={Boolean(error)}
+                aria-describedby={`${id}-help`}
+                onChange={(e) => onFile?.(field.id, e.target.files?.[0])}
+              />
+            ) : field.type === "textarea" ? (
+              <TextArea {...shared} minLength={field.minLength} rows={4} />
+            ) : field.type === "select" ? (
+              <NativeSelect {...shared}>
+                <option value="">—</option>
+                {field.options?.map((option) => (
+                  <option key={option}>{option}</option>
+                ))}
+              </NativeSelect>
+            ) : (
+              <TextInput
+                {...shared}
+                type={field.type ?? "text"}
+                minLength={field.minLength}
+                min={field.min}
+                max={field.max}
+              />
+            )}
+            <small id={`${id}-help`} data-error={Boolean(error)}>
+              {error ||
+                field.hint ||
+                (field.type === "file" ? values[field.id] : "")}
+            </small>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+/** Table is independently scroll-owned. The host supplies filtered rows and exact actions. */
+export function RecordTable({
+  caption,
+  columns,
+  rows,
+  emptyLabel,
+  actionLabel,
+  onOpen,
+}: {
+  caption: string;
+  columns: string[];
+  rows: { id: string; cells: string[] }[];
+  emptyLabel: string;
+  actionLabel: string;
+  onOpen?: (id: string) => void;
+}) {
+  return (
+    <div
+      className="workflow-table-scroll"
+      data-slot="record-table"
+      tabIndex={0}
+      role="region"
+      aria-label={caption}
+    >
+      <table>
+        <caption>{caption}</caption>
+        <thead>
+          <tr>
+            {columns.map((column, i) => (
+              <th scope="col" key={i}>
+                {column}
+              </th>
+            ))}
+            {onOpen ? <th scope="col">{actionLabel}</th> : null}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.length ? (
+            rows.map((row) => (
+              <tr key={row.id}>
+                {row.cells.map((cell, i) => (
+                  <td key={i}>{cell}</td>
+                ))}
+                {onOpen ? (
+                  <td>
+                    <Button
+                      size="sm"
+                      variant="outline"
+                      onClick={() => onOpen(row.id)}
+                      aria-label={`${actionLabel}: ${row.cells[0]}`}
+                    >
+                      {actionLabel}
+                    </Button>
+                  </td>
+                ) : null}
+              </tr>
+            ))
+          ) : (
+            <tr>
+              <td colSpan={columns.length + (onOpen ? 1 : 0)}>{emptyLabel}</td>
+            </tr>
+          )}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+/** Gate states are supplied by the host; a preview cannot verify identity or hardware. */
+export function StepChecklist({
+  items,
+  passLabel,
+  failLabel,
+  onChange,
+}: {
+  items: {
+    id: string;
+    label: string;
+    description: string;
+    state: string;
+    disabled?: boolean;
+  }[];
+  passLabel: string;
+  failLabel: string;
+  onChange: (id: string, state: "pass" | "fail") => void;
+}) {
+  return (
+    <ol className="workflow-checklist" data-slot="step-checklist">
+      {items.map((item) => (
+        <li className="product-card" key={item.id} data-state={item.state}>
+          <strong>{item.label}</strong>
+          <p>{item.description}</p>
+          <div className="product-actions">
+            <Button
+              disabled={item.disabled}
+              aria-pressed={item.state === "pass"}
+              onClick={() => onChange(item.id, "pass")}
+            >
+              {passLabel}
+            </Button>
+            <Button
+              variant="outline"
+              disabled={item.disabled}
+              aria-pressed={item.state === "fail"}
+              onClick={() => onChange(item.id, "fail")}
+            >
+              {failLabel}
+            </Button>
+          </div>
+        </li>
+      ))}
+    </ol>
+  );
+}
+
+export function StatStrip({
+  items,
+}: {
+  items: { label: string; value: string; detail?: string }[];
+}) {
+  return (
+    <dl className="workflow-stats" data-slot="stat-strip">
+      {items.map((item) => (
+        <div className="product-card" key={item.label}>
+          <dt>{item.label}</dt>
+          <dd>{item.value}</dd>
+          {item.detail ? <small>{item.detail}</small> : null}
+        </div>
+      ))}
+    </dl>
+  );
+}
+
+export function RatingFields({
+  labels,
+  values,
+  onChange,
+}: {
+  labels: string[];
+  values: number[];
+  onChange: (index: number, value: number) => void;
+}) {
+  return (
+    <div className="workflow-fields" data-slot="rating-fields">
+      {labels.map((label, index) => (
+        <fieldset className="product-card" key={label}>
+          <legend>{label}</legend>
+          <div className="product-actions">
+            {[1, 2, 3, 4, 5].map((value) => (
+              <Button
+                key={value}
+                variant={values[index] === value ? "default" : "outline"}
+                aria-pressed={values[index] === value}
+                onClick={() => onChange(index, value)}
+                aria-label={`${label}: ${value} / 5`}
+              >
+                {value}
+              </Button>
+            ))}
+          </div>
+        </fieldset>
+      ))}
+    </div>
+  );
+}
+
+export function TrendSummary({
+  title,
+  items,
+}: {
+  title: string;
+  items: { label: string; value: number; max: number }[];
+}) {
+  return (
+    <section className="product-card" data-slot="trend-summary">
+      <h4>{title}</h4>
+      {items.map((item) => (
+        <label className="workflow-field" key={item.label}>
+          <span>
+            {item.label} · {item.value} / {item.max}
+          </span>
+          <meter min={0} max={item.max} value={item.value} />
+        </label>
+      ))}
+    </section>
+  );
+}
+
+/** No camera, microphone, network or recording is started by this visual stage. */
+export function MediaStage({
+  label,
+  status,
+  children,
+}: {
+  label: string;
+  status: string;
+  children?: React.ReactNode;
+}) {
+  return (
+    <section
+      className="workflow-media"
+      data-slot="media-stage"
+      aria-label={label}
+    >
+      <h4>{label}</h4>
+      <p role="status">{status}</p>
+      {children}
+    </section>
+  );
+}