ui: complete and activate the v2 design system

.design-sync/NOTES.md

@@ -4,7 +4,8 @@
 gitignored `.ds-sync` toolchain and compiles CSS into `.design-sync/.cache/compiled.css`.
 Use `node scripts/design-sync.mjs --skip-install` when `.ds-sync` is already populated.
 Remote upload to claude.ai/design (`resync.mjs --remote`) remains a session skill
-outside this lockfile — run it after the local CSS prep when you need a full sync.
+outside this lockfile — run it only with the required authorisation. Local entry/config/preview
+parity does not prove remote upload, remote publication, or remote project state.
 
 - This repo is the Next.js app itself, not a component library: no `dist/`, no
   Storybook. The sync uses the package shape with a hand-authored entry at
@@ -33,7 +34,8 @@ outside this lockfile — run it after the local CSS prep when you need a full s
   transformed, explicitly-sized container (see `previews/Sheet.tsx`) so the
   overlay stays inside the card. Keep that wrapper on any preview edit.
 - Default `guidelinesGlob` swept 46 repo process docs into `guidelines/` —
-  the config pins a curated 5-file design set; keep it curated.
+  the config pins the seven-document `docs/design-system/` set; keep it curated and run
+  `npm run check:design-sync-contract` after changing public APIs or previews.
 
 ## Known claude.ai/design validator findings (accepted, do not "fix")
 

.design-sync/entry.tsx

@@ -2,24 +2,126 @@
 // enumerates the design-layer surface that syncs to claude.ai/design.
 // Components AND the utility class-string vocabulary both ride along.
 export * from "@/components/ui-primitives";
-export { Sheet } from "@/components/ui/sheet";
-export { SafeBoldText } from "@/components/SafeBoldText";
-export { AccessibleTable } from "@/components/AccessibleTable";
-
-// Components added in the v2 pass. They close the gaps the design review found:
-// nothing in the system owned actions, text entry, filter chips, async outcome
-// announcements, in-page section switching, supplementary help text, long-list
-// paging, destructive confirmation, or page-level titling.
-export { Button } from "@/components/ui/button";
-export { TextField, SearchField } from "@/components/ui/text-field";
-export { Chip } from "@/components/ui/chip";
-export { ToastProvider, ToastRegion, useToast } from "@/components/ui/toast";
-export { Tabs } from "@/components/ui/tabs";
-export { Tooltip } from "@/components/ui/tooltip";
-export { Pagination } from "@/components/ui/pagination";
-export { ConfirmDialog } from "@/components/ui/confirm-dialog";
-export { PageHeader, Breadcrumb } from "@/components/ui/page-header";
-export { AnswerCard, AnswerFooter, DoseLine } from "@/components/ui/answer-card";
+export {
+  AccessibleTable,
+  type AccessibleTableColumnAlign,
+  type AccessibleTableProps,
+} from "@/components/AccessibleTable";
+export { SafeBoldText, type SafeBoldTextProps } from "@/components/SafeBoldText";
+export {
+  AnswerCard,
+  AnswerFooter,
+  DoseLine,
+  answerClipboardText,
+  type AnswerCardProps,
+  type AnswerCardAction,
+  type AnswerFooterProps,
+  type DoseQuantity,
+  type DoseLineProps,
+  type DoseRow,
+  type DoseSourceRef,
+} from "@/components/ui/answer-card";
+export {
+  answerStateFromRetrieval,
+  type AnswerState,
+  type DegradedAnswerState,
+  type OverdueSource,
+  type SourceRef,
+  type AnswerStateInput,
+} from "@/components/ui/answer-state";
+export { Button, type ButtonProps, type ButtonSize, type ButtonVariant } from "@/components/ui/button";
+export {
+  Chip,
+  type ChipAppearance,
+  type ChipCategoryTone,
+  type ChipInformationTone,
+  type ChipProps,
+  type ChipSize,
+  type ChipStatusTone,
+} from "@/components/ui/chip";
+export {
+  Checkbox,
+  RadioGroup,
+  type CheckboxProps,
+  type RadioGroupProps,
+  type RadioOption,
+} from "@/components/ui/choice";
+export { Citation, CitationList, type CitationListProps, type CitationProps } from "@/components/ui/citation";
+export { ConfirmDialog, type ConfirmDialogProps } from "@/components/ui/confirm-dialog";
+export { DateDisplay, type DateDisplayKind, type DateDisplayProps } from "@/components/ui/date-display";
+export {
+  Disclosure,
+  DisclosureGroup,
+  type DisclosureGroupProps,
+  type DisclosureProps,
+} from "@/components/ui/disclosure";
+export {
+  ErrorSummary,
+  FieldError,
+  FieldHint,
+  FormField,
+  type ErrorSummaryProps,
+  type FieldErrorProps,
+  type FieldHintProps,
+  type FormFieldRenderProps,
+  type FormFieldProps,
+} from "@/components/ui/form-field";
+export {
+  DownloadLink,
+  ExternalTextLink,
+  LinkAction,
+  TextLink,
+  type DownloadLinkProps,
+  type ExternalTextLinkProps,
+  type LinkActionProps,
+  type TextLinkProps,
+} from "@/components/ui/link";
+export {
+  LiveAnnouncer,
+  RouteAnnouncer,
+  announce,
+  type AnnounceOptions,
+  type AnnouncePriority,
+} from "@/components/ui/live-announcer";
+export { MissingValue, type MissingValueProps, type MissingValueReason } from "@/components/ui/missing-value";
+export { OverlayPortal, OverlayRoot, type OverlayLayer, type OverlayPortalProps } from "@/components/ui/overlay-root";
+export {
+  Breadcrumb,
+  PageHeader,
+  type BreadcrumbProps,
+  type Crumb,
+  type PageHeaderProps,
+} from "@/components/ui/page-header";
+export { Pagination, type PaginationProps } from "@/components/ui/pagination";
+export { Progress, StageList, type ProgressProps, type Stage, type StageListProps } from "@/components/ui/progress";
+export { Quantity, type QuantityProps } from "@/components/ui/quantity";
+export { RetrievalStateBanner, type RetrievalStateBannerProps } from "@/components/ui/retrieval-state-banner";
+export {
+  SegmentedControl,
+  type SegmentedControlOption,
+  type SegmentedControlProps,
+} from "@/components/ui/segmented-control";
+export { Select, type SelectOption, type SelectProps } from "@/components/ui/select";
+export { Sheet, type SheetMobileSize, type SheetProps } from "@/components/ui/sheet";
+export { StatusMark, type DocumentStatus, type StatusMarkProps } from "@/components/ui/status-mark";
+export { Tabs, type TabItem, type TabsProps } from "@/components/ui/tabs";
+export { SearchField, TextField, type SearchFieldProps, type TextFieldProps } from "@/components/ui/text-field";
+export {
+  ToastProvider,
+  ToastRegion,
+  useToast,
+  type Toast,
+  type ToastApi,
+  type ToastInput,
+  type ToastProviderProps,
+} from "@/components/ui/toast";
+export { Tooltip, type TooltipProps } from "@/components/ui/tooltip";
+export {
+  VerificationNotice,
+  type VerificationNoticeProps,
+  type VerificationState,
+} from "@/components/ui/verification-notice";
+export type { NormalizedAccessibleTable } from "@/lib/accessible-table-normalization";
 
 // Curated lucide-react icon set: consumers of the synced bundle have no
 // lucide-react install, so the icons PanelHeading/EmptyState-style `icon`

.design-sync/previews/AnswerCard.tsx

@@ -1,22 +1,20 @@
-import { AnswerCard, AnswerFooter, DoseLine, Chip } from "prompt-for-codex-medical-knowledge-base";
+import { AnswerCard } from "prompt-for-codex-medical-knowledge-base";
+
+const readyState = { kind: "ready", sourceCount: 2 } as const;
+const readyVerification = { state: "ready" } as const;
+const openSource = (_sourceId: string, _locator?: string) => {};
 
 export const WithFooter = () => (
   <div className="w-[40rem]">
     <AnswerCard
-      header={
-        <div className="flex flex-wrap items-center gap-1.5">
-          <Chip tone="success">Current</Chip>
-          <Chip tone="info">WA</Chip>
-        </div>
-      }
-      footer={
-        <AnswerFooter
-          publisher="Sir Charles Gairdner Hospital"
-          version="4.2"
-          reviewDate="18/05/2026"
-          generatedAt="31/07/2026 13:04"
-        />
-      }
+      state={readyState}
+      verification={readyVerification}
+      provenance={{
+        publisher: "Sir Charles Gairdner Hospital",
+        version: "4.2",
+        reviewDate: "2026-05-18",
+        generatedAt: "2026-07-31T13:04:00+08:00",
+      }}
     >
       <p>
         Start clozapine at a low dose and titrate against tolerability, with haematological monitoring weekly for the
@@ -28,16 +26,85 @@ export const WithFooter = () => (
 
 export const PlainAnswer = () => (
   <div className="w-[40rem]">
-    <AnswerCard>
+    <AnswerCard state={readyState} verification={readyVerification}>
       <p>No local guideline covers this question. The linked sources are the closest available.</p>
     </AnswerCard>
   </div>
 );
 
 export const MissingReviewDate = () => (
   <div className="w-[40rem]">
-    <AnswerCard footer={<AnswerFooter publisher="RANZCP" generatedAt="31/07/2026 13:04" />}>
+    <AnswerCard
+      state={readyState}
+      verification={readyVerification}
+      provenance={{ publisher: "RANZCP", generatedAt: "2026-07-31T13:04:00+08:00" }}
+    >
       <p>Review status is unknown for this source, so the footer says so rather than staying blank.</p>
     </AnswerCard>
   </div>
 );
+
+export const StaleEvidence = () => (
+  <div className="w-[40rem]">
+    <AnswerCard
+      state={{
+        kind: "stale_evidence",
+        sourceCount: 2,
+        overdue: [
+          {
+            sourceId: "wa-clozapine-protocol",
+            title: "WA Clozapine Protocol",
+            locator: "p. 18",
+            reviewDueOn: "2025-11-01",
+            status: "review_due",
+          },
+        ],
+      }}
+      verification={{ state: "stale_evidence", sourceCount: 2 }}
+      onOpenSource={openSource}
+    >
+      <p>This answer uses a source whose scheduled review is overdue.</p>
+    </AnswerCard>
+  </div>
+);
+
+export const PartialRetrieval = () => (
+  <div className="w-[40rem]">
+    <AnswerCard
+      state={{
+        kind: "partial_retrieval",
+        retrieved: 2,
+        requested: 3,
+        missing: [{ sourceId: "local-monitoring-addendum", title: "Local monitoring addendum", locator: "p. 4" }],
+      }}
+      verification={{ state: "partial_retrieval", sourceCount: 2 }}
+      onOpenSource={openSource}
+    >
+      <p>This answer may omit local guidance because one named source was unavailable.</p>
+    </AnswerCard>
+  </div>
+);
+
+export const Ungrounded = () => (
+  <div className="w-[40rem]">
+    <AnswerCard
+      state={{ kind: "ungrounded", reason: "unverified_numeric", sourceCount: 2 }}
+      verification={{ state: "ungrounded", sourceCount: 2 }}
+      onOpenSource={openSource}
+    >
+      <p>The cited passages did not verify every clinical number in this answer.</p>
+    </AnswerCard>
+  </div>
+);
+
+export const SourceOnly = () => (
+  <div className="w-[40rem]">
+    <AnswerCard
+      state={{ kind: "source_only", reason: "quality_gate" }}
+      verification={{ state: "source_only", attribution: "extractive", sourceCount: 2 }}
+      onOpenSource={openSource}
+    >
+      <p>This answer was assembled from source passages without model synthesis.</p>
+    </AnswerCard>
+  </div>
+);

.design-sync/previews/AnswerFooter.tsx

@@ -5,16 +5,16 @@ export const Complete = () => (
     <AnswerFooter
       publisher="Sir Charles Gairdner Hospital"
       version="4.2"
-      reviewDate="18/05/2026"
-      generatedAt="31/07/2026 13:04"
+      reviewDate="2026-05-18"
+      generatedAt="2026-07-31T13:04:00+08:00"
     />
   </div>
 );
 
-// Missing segments are dropped rather than filled with "Unknown" - except the
-// review date, which stays explicit because its absence is itself a signal.
+// Missing metadata renders explicit MissingValue phrases for every absent field;
+// nothing is silently dropped from the provenance strip.
 export const SparseMetadata = () => (
   <div className="w-[40rem] overflow-hidden rounded-lg border border-[color:var(--border)]">
-    <AnswerFooter publisher="RANZCP" generatedAt="31/07/2026 13:04" />
+    <AnswerFooter publisher="RANZCP" generatedAt="2026-07-31T13:04:00+08:00" />
   </div>
 );

.design-sync/previews/Checkbox.tsx

@@ -0,0 +1,9 @@
+import { Checkbox } from "prompt-for-codex-medical-knowledge-base";
+
+export const States = () => (
+  <div className="space-y-3">
+    <Checkbox label="Current guidelines only" defaultChecked />
+    <Checkbox label="Include archived sources" description="Archived sources remain visibly marked." />
+    <Checkbox label="Some selected" indeterminate />
+  </div>
+);

.design-sync/previews/Chip.tsx

@@ -1,36 +1,50 @@
 import { Chip } from "prompt-for-codex-medical-knowledge-base";
 import { Filter } from "lucide-react";
 
-export const Tones = () => (
+export const Appearances = () => (
   <div className="flex flex-wrap items-center gap-1.5">
-    <Chip>Neutral</Chip>
-    <Chip tone="info">Registry summary</Chip>
-    <Chip tone="success">Current</Chip>
-    <Chip tone="warning">Review due</Chip>
-    <Chip tone="danger">Outdated</Chip>
+    <Chip appearance={{ kind: "information", tone: "quiet" }}>Supporting detail</Chip>
+    <Chip appearance={{ kind: "category", tone: "document" }}>Document</Chip>
+    <Chip appearance={{ kind: "category", tone: "service" }}>Service</Chip>
+    <Chip appearance={{ kind: "status", tone: "success" }} dot>
+      Current
+    </Chip>
+    <Chip appearance={{ kind: "status", tone: "warning" }} dot>
+      Review due
+    </Chip>
+    <Chip appearance={{ kind: "status", tone: "danger" }} dot>
+      Outdated
+    </Chip>
   </div>
 );
 
-export const WithDot = () => (
+export const Sizes = () => (
   <div className="flex flex-wrap items-center gap-1.5">
-    <Chip dot tone="success">
-      Indexed
-    </Chip>
-    <Chip dot tone="warning">
-      Partial extraction
+    <Chip size="compact" appearance={{ kind: "information", tone: "inset" }}>
+      Compact
     </Chip>
-    <Chip dot tone="neutral">
-      Not started
+    <Chip size="standard" appearance={{ kind: "information", tone: "accent" }}>
+      Standard
     </Chip>
   </div>
 );
 
 export const Removable = () => (
   <div className="flex flex-wrap items-center gap-1.5">
-    <Chip icon={Filter} onRemove={() => {}} removeLabel="Remove filter: WA jurisdiction">
+    <Chip
+      icon={Filter}
+      appearance={{ kind: "information", tone: "accent" }}
+      onRemove={() => {}}
+      removeLabel="Remove filter: WA jurisdiction"
+    >
       WA
     </Chip>
-    <Chip icon={Filter} onRemove={() => {}} removeLabel="Remove filter: current sources only">
+    <Chip
+      icon={Filter}
+      appearance={{ kind: "information", tone: "accent" }}
+      onRemove={() => {}}
+      removeLabel="Remove filter: current sources only"
+    >
       Current only
     </Chip>
   </div>

.design-sync/previews/Citation.tsx

@@ -0,0 +1,9 @@
+import { Citation } from "prompt-for-codex-medical-knowledge-base";
+
+export const CurrentSource = () => (
+  <Citation interactive={false} index={1} label="Therapeutic Guidelines" locator="p. 14" status="current" />
+);
+
+export const ReviewDue = () => (
+  <Citation interactive={false} index={2} label="Local clozapine protocol" locator="§3.2" status="review_due" />
+);