From 2e2e2a5f378a54d661fa6daaa7be4f7904560987 Mon Sep 17 00:00:00 2001
From: David Diviny <david.diviny@gmail.com>
Date: Wed, 8 Apr 2026 06:14:48 +1000
Subject: [PATCH 1/3] Build GovGraph design system foundation

---
 .../web/app/_components/relationship-list.tsx |  49 ++-
 apps/web/app/_components/search-form.tsx      |   4 +-
 apps/web/app/design/page.tsx                  | 279 ++++++++++++++++++
 apps/web/app/globals.css                      |  42 ++-
 apps/web/app/layout.tsx                       |  64 +++-
 apps/web/app/nodes/[slug]/page.tsx            | 215 +++++++++-----
 apps/web/app/not-found.tsx                    |  46 +--
 apps/web/app/page.tsx                         | 277 ++++++++---------
 docs/design-system.md                         |  25 ++
 packages/ui/package.json                      |  12 +-
 packages/ui/scripts/generate-token-css.ts     |  10 +
 packages/ui/src/badge.tsx                     |  30 +-
 packages/ui/src/breadcrumb.tsx                |  45 +++
 packages/ui/src/button.tsx                    |  32 +-
 packages/ui/src/card.tsx                      |  21 +-
 packages/ui/src/data-table-sort.test.ts       |  55 ++++
 packages/ui/src/data-table-sort.ts            |  80 +++++
 packages/ui/src/data-table.tsx                | 141 +++++++++
 packages/ui/src/empty-state.tsx               |  41 +++
 packages/ui/src/footer.tsx                    |  42 +++
 packages/ui/src/index.ts                      |  19 ++
 packages/ui/src/input.tsx                     |   2 +-
 packages/ui/src/key-value.tsx                 |  32 ++
 packages/ui/src/metric-bar.tsx                |  58 ++++
 packages/ui/src/node-card.tsx                 |  43 +++
 packages/ui/src/node-type-badge.tsx           |  62 ++++
 packages/ui/src/page-shell.tsx                |  18 ++
 packages/ui/src/section-header.tsx            |  52 ++++
 packages/ui/src/site-header.tsx               |  37 +++
 packages/ui/src/skeleton.tsx                  |  31 ++
 packages/ui/src/source-card.tsx               |  44 +++
 packages/ui/src/stat-card.tsx                 |  32 ++
 packages/ui/src/textarea.tsx                  |  18 ++
 packages/ui/src/timeline-entry.tsx            |  45 +++
 packages/ui/src/tokens/animation.ts           |  10 +
 packages/ui/src/tokens/colors.ts              |  97 ++++++
 packages/ui/src/tokens/generate-css.ts        |  49 +++
 packages/ui/src/tokens/generated.css          | 143 +++++++++
 packages/ui/src/tokens/index.test.ts          |  26 ++
 packages/ui/src/tokens/index.ts               |  46 +++
 packages/ui/src/tokens/radii.ts               |   8 +
 packages/ui/src/tokens/shadows.ts             |   5 +
 packages/ui/src/tokens/spacing.ts             |  15 +
 packages/ui/src/tokens/typography.ts          |  57 ++++
 packages/ui/src/tooltip.tsx                   |  27 ++
 packages/ui/tsconfig.json                     |   3 +
 46 files changed, 2173 insertions(+), 316 deletions(-)
 create mode 100644 apps/web/app/design/page.tsx
 create mode 100644 docs/design-system.md
 create mode 100644 packages/ui/scripts/generate-token-css.ts
 create mode 100644 packages/ui/src/breadcrumb.tsx
 create mode 100644 packages/ui/src/data-table-sort.test.ts
 create mode 100644 packages/ui/src/data-table-sort.ts
 create mode 100644 packages/ui/src/data-table.tsx
 create mode 100644 packages/ui/src/empty-state.tsx
 create mode 100644 packages/ui/src/footer.tsx
 create mode 100644 packages/ui/src/key-value.tsx
 create mode 100644 packages/ui/src/metric-bar.tsx
 create mode 100644 packages/ui/src/node-card.tsx
 create mode 100644 packages/ui/src/node-type-badge.tsx
 create mode 100644 packages/ui/src/page-shell.tsx
 create mode 100644 packages/ui/src/section-header.tsx
 create mode 100644 packages/ui/src/site-header.tsx
 create mode 100644 packages/ui/src/skeleton.tsx
 create mode 100644 packages/ui/src/source-card.tsx
 create mode 100644 packages/ui/src/stat-card.tsx
 create mode 100644 packages/ui/src/textarea.tsx
 create mode 100644 packages/ui/src/timeline-entry.tsx
 create mode 100644 packages/ui/src/tokens/animation.ts
 create mode 100644 packages/ui/src/tokens/colors.ts
 create mode 100644 packages/ui/src/tokens/generate-css.ts
 create mode 100644 packages/ui/src/tokens/generated.css
 create mode 100644 packages/ui/src/tokens/index.test.ts
 create mode 100644 packages/ui/src/tokens/index.ts
 create mode 100644 packages/ui/src/tokens/radii.ts
 create mode 100644 packages/ui/src/tokens/shadows.ts
 create mode 100644 packages/ui/src/tokens/spacing.ts
 create mode 100644 packages/ui/src/tokens/typography.ts
 create mode 100644 packages/ui/src/tooltip.tsx

diff --git a/apps/web/app/_components/relationship-list.tsx b/apps/web/app/_components/relationship-list.tsx
index 818f4f8..9692ef4 100644
--- a/apps/web/app/_components/relationship-list.tsx
+++ b/apps/web/app/_components/relationship-list.tsx
@@ -1,9 +1,9 @@
 import Link from "next/link";
 
 import type { RelatedNode } from "@govgraph/domain";
-import { Badge, Card } from "@govgraph/ui";
+import { Badge, EmptyState, NodeCard, NodeTypeBadge } from "@govgraph/ui";
 
-import { describeRelationship, humanizeNodeType } from "../_lib/presenters";
+import { describeRelationship } from "../_lib/presenters";
 
 type RelationshipListProps = {
   relatedNodes: RelatedNode[];
@@ -12,37 +12,34 @@ type RelationshipListProps = {
 export function RelationshipList({ relatedNodes }: RelationshipListProps) {
   if (relatedNodes.length === 0) {
     return (
-      <Card className="p-6">
-        <p className="text-sm text-[var(--govgraph-muted)]">
-          No connected records are available for this node yet.
-        </p>
-      </Card>
+      <EmptyState
+        description="This record is in the live snapshot, but its relationships have not been connected yet."
+        title="No linked records yet"
+      />
     );
   }
 
   return (
     <div className="grid gap-4">
       {relatedNodes.map((entry) => (
-        <Card
+        <NodeCard
           key={`${entry.edgeType}-${entry.direction}-${entry.node.id}`}
-          className="p-5 transition-transform duration-200 hover:-translate-y-0.5"
-        >
-          <div className="flex flex-wrap items-center gap-3">
-            <Badge>{describeRelationship(entry)}</Badge>
-            <Badge>{humanizeNodeType(entry.node.nodeType)}</Badge>
-          </div>
-          <Link
-            href={`/nodes/${entry.node.slug}`}
-            className="mt-4 block text-xl font-semibold tracking-tight text-[var(--govgraph-ink)] underline-offset-4 hover:underline"
-          >
-            {entry.node.canonicalName}
-          </Link>
-          {entry.node.description ? (
-            <p className="mt-2 max-w-3xl text-sm leading-6 text-[var(--govgraph-muted)]">
-              {entry.node.description}
-            </p>
-          ) : null}
-        </Card>
+          badges={
+            <>
+              <Badge>{describeRelationship(entry)}</Badge>
+              <NodeTypeBadge nodeType={entry.node.nodeType} />
+            </>
+          }
+          description={entry.node.description}
+          title={
+            <Link
+              href={`/nodes/${entry.node.slug}`}
+              className="underline-offset-4 hover:underline"
+            >
+              {entry.node.canonicalName}
+            </Link>
+          }
+        />
       ))}
     </div>
   );
diff --git a/apps/web/app/_components/search-form.tsx b/apps/web/app/_components/search-form.tsx
index 5b4826b..af357a3 100644
--- a/apps/web/app/_components/search-form.tsx
+++ b/apps/web/app/_components/search-form.tsx
@@ -4,12 +4,14 @@ type SearchFormProps = {
   defaultValue?: string;
   action?: string;
   placeholder?: string;
+  size?: "md" | "lg";
 };
 
 export function SearchForm({
   defaultValue = "",
   action = "/",
   placeholder = "Search ministers, portfolios, and departments",
+  size = "lg",
 }: SearchFormProps) {
   return (
     <form action={action} className="flex flex-col gap-3 sm:flex-row">
@@ -20,7 +22,7 @@ export function SearchForm({
         aria-label="Search the government map"
         className="min-w-0 flex-1"
       />
-      <Button type="submit" className="min-w-32">
+      <Button type="submit" className="min-w-32" size={size}>
         Search
       </Button>
     </form>
diff --git a/apps/web/app/design/page.tsx b/apps/web/app/design/page.tsx
new file mode 100644
index 0000000..3fe46dd
--- /dev/null
+++ b/apps/web/app/design/page.tsx
@@ -0,0 +1,279 @@
+import Link from "next/link";
+
+import { nodeTypes } from "@govgraph/domain";
+import {
+  Badge,
+  Button,
+  Card,
+  DataTable,
+  EmptyState,
+  KeyValue,
+  MetricBar,
+  NodeCard,
+  NodeTypeBadge,
+  PageShell,
+  SectionHeader,
+  Skeleton,
+  SourceCard,
+  StatCard,
+  Textarea,
+  TimelineEntry,
+  Tooltip,
+  Input,
+} from "@govgraph/ui";
+
+const budgetRows = [
+  { agency: "Treasury and Finance", budget: 8300000000, workforce: 1450 },
+  { agency: "Transport and Planning", budget: 16700000000, workforce: 3940 },
+  { agency: "Education", budget: 23200000000, workforce: 2180 },
+] as const;
+
+const budgetColumns = [
+  { key: "agency", header: "Agency", sortable: true },
+  {
+    key: "budget",
+    header: "Budget",
+    sortable: true,
+    align: "right" as const,
+    format: "currency" as const,
+  },
+  {
+    key: "workforce",
+    header: "Workforce",
+    sortable: true,
+    align: "right" as const,
+    format: "number" as const,
+  },
+] as const;
+
+export default function DesignPage() {
+  return (
+    <main>
+      <PageShell className="gap-[var(--gg-space-10)]">
+        <section className="space-y-[var(--gg-space-5)] rounded-[var(--gg-radius-2xl)] border border-[var(--gg-color-border)] bg-[color:rgba(255,250,241,0.8)] p-[var(--gg-space-8)] shadow-[var(--gg-shadow-lg)]">
+          <div className="flex flex-wrap gap-[var(--gg-space-3)]">
+            <Badge tone="accent">GovGraph Design System</Badge>
+            <Badge tone="success">Live preview route</Badge>
+          </div>
+          <div className="space-y-[var(--gg-space-3)]">
+            <p className="text-[length:var(--gg-font-size-xs)] font-semibold uppercase tracking-[var(--gg-font-letter-spacing-eyebrow)] text-[var(--gg-color-semantic-text-secondary)]">
+              Register aesthetic
+            </p>
+            <h1 className="max-w-4xl font-[family-name:var(--gg-font-family-display)] text-[length:var(--gg-font-size-5xl)] font-semibold tracking-[var(--gg-font-letter-spacing-tight)] text-[var(--gg-color-ink)] sm:text-[length:var(--gg-font-size-6xl)]">
+              Typed tokens, shared components, and a calmer way to build the
+              atlas.
+            </h1>
+            <p className="max-w-3xl text-[length:var(--gg-font-size-lg)] leading-[var(--gg-font-line-height-relaxed)] text-[var(--gg-color-semantic-text-secondary)]">
+              This page previews the shared system that now drives the live
+              pages. It is where new patterns should be checked before they land
+              in the atlas proper.
+            </p>
+          </div>
+        </section>
+
+        <section className="grid gap-[var(--gg-space-6)] lg:grid-cols-3">
+          <StatCard
+            label="Token groups"
+            value="6"
+            description="Colour, type, spacing, radii, shadows, and motion now live in one typed source."
+          />
+          <StatCard
+            label="Node tones"
+            value={nodeTypes.length}
+            description="Every node type has a distinct badge treatment for faster scanning."
+          />
+          <StatCard
+            label="Preview route"
+            value="/design"
+            description="A simple in-app showcase beats an unmaintained component playground at this stage."
+          />
+        </section>
+
+        <section className="grid gap-[var(--gg-space-6)] lg:grid-cols-[0.9fr_1.1fr]">
+          <div className="space-y-[var(--gg-space-4)]">
+            <SectionHeader
+              eyebrow="Foundation"
+              title="Actions and form controls"
+              description="Buttons, badges, fields, and text areas all pull from the same token set."
+            />
+            <Card className="space-y-[var(--gg-space-5)] p-[var(--gg-space-6)]">
+              <div className="flex flex-wrap gap-[var(--gg-space-3)]">
+                <Button size="sm">Search</Button>
+                <Button size="md" tone="ghost">
+                  Secondary
+                </Button>
+                <Button size="lg" tone="danger">
+                  Remove
+                </Button>
+              </div>
+              <div className="flex flex-wrap gap-[var(--gg-space-3)]">
+                <Badge>Neutral</Badge>
+                <Badge tone="accent">Accent</Badge>
+                <Badge tone="success">Success</Badge>
+                <Badge tone="warning">Warning</Badge>
+              </div>
+              <div className="space-y-[var(--gg-space-3)]">
+                <Input placeholder="Search ministers, portfolios, and departments" />
+                <Textarea placeholder="Notes, source caveats, or editorial guidance." />
+              </div>
+            </Card>
+          </div>
+
+          <div className="space-y-[var(--gg-space-4)]">
+            <SectionHeader
+              eyebrow="Tones"
+              title="Node-type badges"
+              description="The atlas can now signal record categories consistently instead of inventing a new label style on every page."
+            />
+            <Card className="flex flex-wrap gap-[var(--gg-space-3)] p-[var(--gg-space-6)]">
+              {nodeTypes.map((nodeType) => (
+                <NodeTypeBadge key={nodeType} nodeType={nodeType} />
+              ))}
+            </Card>
+          </div>
+        </section>
+
+        <section className="grid gap-[var(--gg-space-6)] lg:grid-cols-[1.1fr_0.9fr]">
+          <div className="space-y-[var(--gg-space-4)]">
+            <SectionHeader
+              eyebrow="Records"
+              title="Cards for nodes and sources"
+              description="These are the shared display patterns that now power the live atlas pages."
+            />
+            <div className="grid gap-[var(--gg-space-4)]">
+              <NodeCard
+                badges={
+                  <>
+                    <NodeTypeBadge nodeType="department" />
+                    <Badge tone="muted">Lead delivery agency</Badge>
+                  </>
+                }
+                description="Supports the education portfolio, child policy, and statewide school governance."
+                footer={
+                  <Link
+                    href="/"
+                    className="text-[length:var(--gg-font-size-sm)] font-medium text-[var(--gg-color-deep)] underline-offset-4 hover:underline"
+                  >
+                    Open record
+                  </Link>
+                }
+                title="Department of Education"
+              />
+              <SourceCard
+                action={
+                  <a
+                    href="https://www.vpsc.vic.gov.au/"
+                    className="text-[length:var(--gg-font-size-sm)] font-medium text-[var(--gg-color-accent)] underline-offset-4 hover:underline"
+                  >
+                    Open source
+                  </a>
+                }
+                badges={
+                  <>
+                    <Badge>VPSC</Badge>
+                    <Badge tone="muted">HTML</Badge>
+                  </>
+                }
+                description="Published by Victorian Public Sector Commission • effective 2025-06-05"
+                metadata="Portfolio mapping"
+                title="Working with Ministers and Ministerial Officers"
+              />
+            </div>
+          </div>
+
+          <div className="space-y-[var(--gg-space-4)]">
+            <SectionHeader
+              eyebrow="Details"
+              title="Compact data patterns"
+              description="Key-value rows and bars give us a cleaner way to show structured facts without falling back to ad hoc grids."
+            />
+            <Card className="space-y-[var(--gg-space-5)] p-[var(--gg-space-6)]">
+              <dl>
+                <KeyValue label="Portfolio group" value="Education" />
+                <KeyValue label="Supporting department" value="Department of Education" />
+                <KeyValue label="Current ministry" value="Allan Ministry" />
+              </dl>
+              <MetricBar
+                detail="Share of a fictional 25,000 workforce comparator used for previewing."
+                label="Education workforce"
+                max={25000}
+                value={2180}
+              />
+              <MetricBar
+                detail="Illustrative budget bar for future fiscal comparisons."
+                label="Transport budget"
+                max={25000000000}
+                tone="deep"
+                value={16700000000}
+                valueLabel="$16.7B"
+              />
+            </Card>
+          </div>
+        </section>
+
+        <section className="space-y-[var(--gg-space-4)]">
+          <SectionHeader
+            eyebrow="Data"
+            title="Sortable tables"
+            description="Budget and workforce views can use one shared table rather than inventing a fresh layout every time."
+            trailing={
+              <Tooltip content="Columns marked SORT can be reordered directly in the table.">
+                <span className="inline-flex rounded-[var(--gg-radius-full)] border border-[var(--gg-color-border)] px-[var(--gg-space-3)] py-[var(--gg-space-1)] text-[length:var(--gg-font-size-xs)] font-semibold uppercase tracking-[var(--gg-font-letter-spacing-caps)]">
+                  Table help
+                </span>
+              </Tooltip>
+            }
+          />
+          <DataTable
+            caption="Illustrative budget and workforce table"
+            columns={budgetColumns}
+            rows={budgetRows}
+          />
+        </section>
+
+        <section className="grid gap-[var(--gg-space-6)] lg:grid-cols-[1fr_1fr]">
+          <div className="space-y-[var(--gg-space-4)]">
+            <SectionHeader
+              eyebrow="States"
+              title="Empty and loading surfaces"
+              description="The quiet states now match the rest of the product instead of dropping back to generic placeholders."
+            />
+            <EmptyState
+              action={<Button tone="ghost">Clear filters</Button>}
+              description="Try a broader search phrase or remove a filter to bring records back into view."
+              title="No records match this combination"
+            />
+            <Card className="space-y-[var(--gg-space-3)] p-[var(--gg-space-6)]">
+              <Skeleton className="w-32" />
+              <Skeleton className="w-full" />
+              <Skeleton className="w-4/5" />
+              <Skeleton shape="card" />
+            </Card>
+          </div>
+
+          <div className="space-y-[var(--gg-space-4)]">
+            <SectionHeader
+              eyebrow="Timeline"
+              title="Event cards"
+              description="Machinery-of-government changes can use a consistent dated entry instead of bespoke page markup."
+            />
+            <div className="grid gap-[var(--gg-space-4)]">
+              <TimelineEntry
+                date="5 December 2024"
+                description="Portfolio responsibilities were regrouped under a simplified education cluster."
+                detail="Machinery of Government"
+                title="Education portfolio updated"
+              />
+              <TimelineEntry
+                date="7 February 2025"
+                description="Source parsing refreshed after the latest parliamentary ministry page update."
+                detail="Source refresh"
+                title="Current ministry snapshot regenerated"
+              />
+            </div>
+          </div>
+        </section>
+      </PageShell>
+    </main>
+  );
+}
diff --git a/apps/web/app/globals.css b/apps/web/app/globals.css
index 0918ae8..42a9fd6 100644
--- a/apps/web/app/globals.css
+++ b/apps/web/app/globals.css
@@ -1,17 +1,8 @@
 @import "tailwindcss";
-
-:root {
-  --govgraph-paper: #f6f1e6;
-  --govgraph-ink: #0e2c24;
-  --govgraph-deep: #163e35;
-  --govgraph-accent: #b94a37;
-  --govgraph-border: rgba(14, 44, 36, 0.14);
-  --govgraph-muted: #5a675f;
-  --govgraph-wash: #edf1eb;
-}
+@import "@govgraph/ui/tokens.css";
 
 html {
-  background: var(--govgraph-paper);
+  background: var(--gg-color-paper);
 }
 
 body {
@@ -20,9 +11,9 @@ body {
     linear-gradient(180deg, rgba(255, 255, 255, 0.65), rgba(246, 241, 230, 1)),
     radial-gradient(circle at top left, rgba(32, 96, 79, 0.18), transparent 28%),
     radial-gradient(circle at bottom right, rgba(185, 74, 55, 0.12), transparent 24%),
-    var(--govgraph-paper);
-  color: var(--govgraph-ink);
-  font-family: var(--font-body), sans-serif;
+    var(--gg-color-paper);
+  color: var(--gg-color-ink);
+  font-family: var(--gg-font-family-body);
 }
 
 body::before {
@@ -40,21 +31,28 @@ body::before {
 h1,
 h2,
 h3 {
-  font-family: var(--font-display), serif;
+  font-family: var(--gg-font-family-display);
 }
 
 code,
 pre {
-  font-family: var(--font-mono), monospace;
+  font-family: var(--gg-font-family-mono);
 }
 
 a,
 button,
-input {
+input,
+textarea {
   transition:
-    color 160ms ease,
-    border-color 160ms ease,
-    background-color 160ms ease,
-    transform 160ms ease,
-    box-shadow 160ms ease;
+    color var(--gg-animation-duration-normal) var(--gg-animation-easing-standard),
+    border-color var(--gg-animation-duration-normal) var(--gg-animation-easing-standard),
+    background-color var(--gg-animation-duration-normal)
+      var(--gg-animation-easing-standard),
+    transform var(--gg-animation-duration-normal) var(--gg-animation-easing-standard),
+    box-shadow var(--gg-animation-duration-normal) var(--gg-animation-easing-standard);
+}
+
+::selection {
+  background: rgba(185, 74, 55, 0.18);
+  color: var(--gg-color-ink);
 }
diff --git a/apps/web/app/layout.tsx b/apps/web/app/layout.tsx
index 8cd532c..f71d0fa 100644
--- a/apps/web/app/layout.tsx
+++ b/apps/web/app/layout.tsx
@@ -1,5 +1,8 @@
 import type { Metadata } from "next";
 import { IBM_Plex_Mono, IBM_Plex_Sans, Newsreader } from "next/font/google";
+import Link from "next/link";
+import { Badge, Footer, SiteHeader } from "@govgraph/ui";
+
 import "./globals.css";
 
 const display = Newsreader({
@@ -34,7 +37,66 @@ export default function RootLayout({
       <body
         className={`${display.variable} ${body.variable} ${mono.variable} antialiased`}
       >
-        {children}
+        <div className="flex min-h-screen flex-col">
+          <SiteHeader
+            brand={
+              <div className="space-y-[var(--gg-space-1)]">
+                <Link
+                  href="/"
+                  className="font-[family-name:var(--gg-font-family-display)] text-[length:var(--gg-font-size-2xl)] font-semibold tracking-[var(--gg-font-letter-spacing-tight)] text-[var(--gg-color-ink)]"
+                >
+                  GovGraph
+                </Link>
+                <p className="text-[length:var(--gg-font-size-xs)] font-semibold uppercase tracking-[var(--gg-font-letter-spacing-caps)] text-[var(--gg-color-semantic-text-secondary)]">
+                  Official register interface
+                </p>
+              </div>
+            }
+            navigation={
+              <>
+                <Link href="/" className="underline-offset-4 hover:text-[var(--gg-color-deep)] hover:underline">
+                  Atlas
+                </Link>
+                <Link href="/design" className="underline-offset-4 hover:text-[var(--gg-color-deep)] hover:underline">
+                  Design
+                </Link>
+              </>
+            }
+            utility={<Badge tone="accent">Prototype</Badge>}
+          />
+          <div className="flex-1">{children}</div>
+          <Footer
+            links={
+              <div className="flex flex-wrap gap-[var(--gg-space-4)]">
+                <Link href="/" className="underline-offset-4 hover:text-[var(--gg-color-deep)] hover:underline">
+                  Home
+                </Link>
+                <Link href="/design" className="underline-offset-4 hover:text-[var(--gg-color-deep)] hover:underline">
+                  Design System
+                </Link>
+                <a
+                  href="https://www.parliament.vic.gov.au/portfolios/"
+                  className="underline-offset-4 hover:text-[var(--gg-color-deep)] hover:underline"
+                >
+                  Parliament Source
+                </a>
+              </div>
+            }
+            meta={
+              <p>
+                Built on official-source-first parsing with register-style UI
+                primitives shared across the app.
+              </p>
+            }
+            summary={
+              <p>
+                GovGraph turns Victorian Government structures into a readable
+                public register, with warm paper surfaces, deep-ink typography,
+                and every visible record anchored to source material.
+              </p>
+            }
+          />
+        </div>
       </body>
     </html>
   );
diff --git a/apps/web/app/nodes/[slug]/page.tsx b/apps/web/app/nodes/[slug]/page.tsx
index d274a2c..d0dff3a 100644
--- a/apps/web/app/nodes/[slug]/page.tsx
+++ b/apps/web/app/nodes/[slug]/page.tsx
@@ -4,11 +4,20 @@ import { notFound } from "next/navigation";
 
 import { getNodeProfile } from "@govgraph/domain";
 import { loadGovernmentCatalog } from "@govgraph/parsers";
-import { Badge, Card } from "@govgraph/ui";
+import {
+  Badge,
+  Breadcrumb,
+  Card,
+  KeyValue,
+  NodeTypeBadge,
+  PageShell,
+  SectionHeader,
+  SourceCard,
+} from "@govgraph/ui";
 
 import { RelationshipList } from "../../_components/relationship-list";
 import { SearchForm } from "../../_components/search-form";
-import { humanizeNodeType, humanizeSourceFamily } from "../../_lib/presenters";
+import { humanizeSourceFamily } from "../../_lib/presenters";
 
 type NodePageProps = {
   params: Promise<{ slug: string }>;
@@ -45,92 +54,136 @@ export default async function NodePage({ params }: NodePageProps) {
   }
 
   return (
-    <main className="mx-auto flex min-h-screen w-full max-w-6xl flex-col gap-8 px-6 py-8 sm:px-8 lg:px-10 lg:py-12">
-      <header className="grid gap-8 rounded-[2rem] border border-[var(--govgraph-border)] bg-white/75 p-6 shadow-[0_24px_80px_rgba(14,44,36,0.08)] backdrop-blur-sm lg:grid-cols-[1.3fr_0.7fr] lg:p-8">
-        <div className="space-y-5">
-          <Link
-            href="/"
-            className="inline-flex text-sm font-medium uppercase tracking-[0.2em] text-[var(--govgraph-muted)] underline-offset-4 hover:underline"
-          >
-            Back to atlas
-          </Link>
-          <div className="flex flex-wrap gap-3">
-            <Badge>{humanizeNodeType(profile.node.nodeType)}</Badge>
-            <Badge>{profile.relatedNodes.length} linked records</Badge>
-          </div>
-          <div className="space-y-3">
-            <h1 className="max-w-4xl text-4xl font-semibold tracking-tight text-[var(--govgraph-ink)] sm:text-5xl">
-              {profile.node.canonicalName}
-            </h1>
-            <p className="max-w-3xl text-base leading-7 text-[var(--govgraph-muted)] sm:text-lg">
-              {profile.node.description ??
-                "This node is part of the current government map snapshot."}
-            </p>
-            {profile.node.websiteUrl ? (
-              <a
-                href={profile.node.websiteUrl}
-                className="inline-flex text-sm font-medium text-[var(--govgraph-accent)] underline-offset-4 hover:underline"
-              >
-                Open official page
-              </a>
-            ) : null}
+    <main>
+      <PageShell className="gap-[var(--gg-space-10)]">
+        <header className="grid gap-[var(--gg-space-8)] rounded-[var(--gg-radius-xl)] border border-[var(--gg-color-border)] bg-[color:rgba(255,255,255,0.74)] p-[var(--gg-space-6)] shadow-[var(--gg-shadow-lg)] backdrop-blur-sm lg:grid-cols-[1.3fr_0.7fr] lg:p-[var(--gg-space-8)]">
+          <div className="space-y-[var(--gg-space-5)]">
+            <Breadcrumb
+              items={[
+                {
+                  content: (
+                    <Link href="/" className="underline-offset-4 hover:underline">
+                      Home
+                    </Link>
+                  ),
+                },
+                {
+                  content: (
+                    <span>{profile.node.nodeType.replace(/_/g, " ")}</span>
+                  ),
+                },
+                {
+                  content: <span>{profile.node.canonicalName}</span>,
+                  current: true,
+                },
+              ]}
+            />
+            <div className="flex flex-wrap gap-[var(--gg-space-3)]">
+              <NodeTypeBadge nodeType={profile.node.nodeType} />
+              <Badge tone="muted">{profile.relatedNodes.length} linked records</Badge>
+            </div>
+            <div className="space-y-[var(--gg-space-3)]">
+              <h1 className="max-w-4xl font-[family-name:var(--gg-font-family-display)] text-[length:var(--gg-font-size-4xl)] font-semibold tracking-[var(--gg-font-letter-spacing-tight)] text-[var(--gg-color-ink)] sm:text-[length:var(--gg-font-size-5xl)]">
+                {profile.node.canonicalName}
+              </h1>
+              <p className="max-w-3xl text-[length:var(--gg-font-size-base)] leading-[var(--gg-font-line-height-body)] text-[var(--gg-color-semantic-text-secondary)] sm:text-[length:var(--gg-font-size-lg)]">
+                {profile.node.description ??
+                  "This node is part of the current government map snapshot."}
+              </p>
+              {profile.node.websiteUrl ? (
+                <a
+                  href={profile.node.websiteUrl}
+                  className="inline-flex text-[length:var(--gg-font-size-sm)] font-medium text-[var(--gg-color-accent)] underline-offset-4 hover:underline"
+                >
+                  Open official page
+                </a>
+              ) : null}
+            </div>
           </div>
-        </div>
 
-        <Card className="p-5">
-          <p className="text-xs font-semibold uppercase tracking-[0.18em] text-[var(--govgraph-muted)]">
-            Search again
-          </p>
-          <div className="mt-4">
-            <SearchForm />
+          <div className="grid gap-[var(--gg-space-4)]">
+            <Card className="p-[var(--gg-space-5)]">
+              <p className="text-[length:var(--gg-font-size-xs)] font-semibold uppercase tracking-[var(--gg-font-letter-spacing-caps)] text-[var(--gg-color-semantic-text-secondary)]">
+                Search again
+              </p>
+              <div className="mt-[var(--gg-space-4)]">
+                <SearchForm size="md" />
+              </div>
+            </Card>
+            <Card className="p-[var(--gg-space-5)]" tone="muted">
+              <p className="text-[length:var(--gg-font-size-xs)] font-semibold uppercase tracking-[var(--gg-font-letter-spacing-caps)] text-[var(--gg-color-semantic-text-secondary)]">
+                Record summary
+              </p>
+              <dl className="mt-[var(--gg-space-4)]">
+                <KeyValue
+                  label="Node type"
+                  value={profile.node.nodeType.replace(/_/g, " ")}
+                />
+                <KeyValue
+                  label="Connected records"
+                  value={profile.relatedNodes.length.toString()}
+                />
+                <KeyValue
+                  label="Source citations"
+                  value={profile.citations.length.toString()}
+                />
+              </dl>
+            </Card>
           </div>
-        </Card>
-      </header>
+        </header>
 
-      <section className="grid gap-6 lg:grid-cols-[1.25fr_0.75fr]">
-        <div className="space-y-4">
-          <div className="flex items-center justify-between gap-4">
-            <h2 className="text-2xl font-semibold tracking-tight text-[var(--govgraph-ink)]">
-              Connected records
-            </h2>
-            <p className="text-sm text-[var(--govgraph-muted)]">
-              Current snapshot
-            </p>
+        <section className="grid gap-[var(--gg-space-6)] lg:grid-cols-[1.25fr_0.75fr]">
+          <div className="space-y-[var(--gg-space-4)]">
+            <SectionHeader
+              title="Connected records"
+              trailing={
+                <span className="inline-flex rounded-[var(--gg-radius-full)] border border-[var(--gg-color-border)] px-[var(--gg-space-3)] py-[var(--gg-space-1)] text-[length:var(--gg-font-size-xs)] font-semibold uppercase tracking-[var(--gg-font-letter-spacing-caps)]">
+                  Current snapshot
+                </span>
+              }
+            />
+            <RelationshipList relatedNodes={profile.relatedNodes} />
           </div>
-          <RelationshipList relatedNodes={profile.relatedNodes} />
-        </div>
 
-        <div className="space-y-4">
-          <h2 className="text-2xl font-semibold tracking-tight text-[var(--govgraph-ink)]">
-            Sources
-          </h2>
-          <div className="grid gap-4">
-            {profile.citations.map((citation) => (
-              <Card key={citation.id} className="p-5">
-                <div className="flex flex-wrap gap-3">
-                  <Badge>{humanizeSourceFamily(citation.sourceFamily)}</Badge>
-                  <Badge>{citation.sourceType}</Badge>
-                </div>
-                <h3 className="mt-4 text-lg font-semibold text-[var(--govgraph-ink)]">
-                  {citation.title}
-                </h3>
-                <p className="mt-2 text-sm leading-6 text-[var(--govgraph-muted)]">
-                  Published by {citation.publisher}
-                  {citation.effectiveDate
-                    ? ` • effective ${citation.effectiveDate}`
-                    : ""}
-                </p>
-                <a
-                  href={citation.sourceUrl}
-                  className="mt-4 inline-flex text-sm font-medium text-[var(--govgraph-accent)] underline-offset-4 hover:underline"
-                >
-                  Open source
-                </a>
-              </Card>
-            ))}
+          <div className="space-y-[var(--gg-space-4)]">
+            <SectionHeader
+              title="Sources"
+              description="Every visible fact on this page should trace back to one of these cited records."
+            />
+            <div className="grid gap-[var(--gg-space-4)]">
+              {profile.citations.map((citation) => (
+                <SourceCard
+                  key={citation.id}
+                  action={
+                    <a
+                      href={citation.sourceUrl}
+                      className="inline-flex text-[length:var(--gg-font-size-sm)] font-medium text-[var(--gg-color-accent)] underline-offset-4 hover:underline"
+                    >
+                      Open source
+                    </a>
+                  }
+                  badges={
+                    <>
+                      <Badge>{humanizeSourceFamily(citation.sourceFamily)}</Badge>
+                      <Badge tone="muted">{citation.sourceType}</Badge>
+                    </>
+                  }
+                  description={
+                    <>
+                      Published by {citation.publisher}
+                      {citation.effectiveDate
+                        ? ` • effective ${citation.effectiveDate}`
+                        : ""}
+                    </>
+                  }
+                  metadata={citation.id}
+                  title={citation.title}
+                />
+              ))}
+            </div>
           </div>
-        </div>
-      </section>
+        </section>
+      </PageShell>
     </main>
   );
 }
diff --git a/apps/web/app/not-found.tsx b/apps/web/app/not-found.tsx
index c669103..6a8c584 100644
--- a/apps/web/app/not-found.tsx
+++ b/apps/web/app/not-found.tsx
@@ -1,30 +1,32 @@
 import Link from "next/link";
 
-import { Card } from "@govgraph/ui";
+import { Card, PageShell } from "@govgraph/ui";
 
 export default function NotFound() {
   return (
-    <main className="mx-auto flex min-h-screen max-w-3xl items-center justify-center px-6 py-12">
-      <Card className="w-full p-8 text-center">
-        <p className="text-xs font-semibold uppercase tracking-[0.2em] text-[var(--govgraph-muted)]">
-          Missing node
-        </p>
-        <h1 className="mt-4 text-4xl font-semibold tracking-tight text-[var(--govgraph-ink)]">
-          This record isn&apos;t in the current snapshot.
-        </h1>
-        <p className="mt-4 text-base leading-7 text-[var(--govgraph-muted)]">
-          The sprint 1 prototype only includes the current ministry, current
-          portfolio mapping, and department-backed portfolio relationships.
-        </p>
-        <div className="mt-8">
-          <Link
-            href="/"
-            className="inline-flex items-center justify-center rounded-full border border-[var(--govgraph-ink)] bg-[var(--govgraph-ink)] px-4 py-2 text-sm font-semibold text-[var(--govgraph-paper)] transition duration-150 hover:bg-[var(--govgraph-deep)]"
-          >
-            Return home
-          </Link>
-        </div>
-      </Card>
+    <main>
+      <PageShell className="min-h-[70vh] items-center justify-center">
+        <Card className="w-full max-w-3xl p-[var(--gg-space-8)] text-center">
+          <p className="text-[length:var(--gg-font-size-xs)] font-semibold uppercase tracking-[var(--gg-font-letter-spacing-eyebrow)] text-[var(--gg-color-semantic-text-secondary)]">
+            Missing node
+          </p>
+          <h1 className="mt-[var(--gg-space-4)] font-[family-name:var(--gg-font-family-display)] text-[length:var(--gg-font-size-4xl)] font-semibold tracking-[var(--gg-font-letter-spacing-tight)] text-[var(--gg-color-ink)]">
+            This record isn&apos;t in the current snapshot.
+          </h1>
+          <p className="mt-[var(--gg-space-4)] text-[length:var(--gg-font-size-base)] leading-[var(--gg-font-line-height-body)] text-[var(--gg-color-semantic-text-secondary)]">
+            The sprint 1 prototype only includes the current ministry, current
+            portfolio mapping, and department-backed portfolio relationships.
+          </p>
+          <div className="mt-[var(--gg-space-8)]">
+            <Link
+              href="/"
+              className="inline-flex min-h-[2.9rem] items-center justify-center rounded-[var(--gg-radius-full)] border border-[var(--gg-color-ink)] bg-[var(--gg-color-ink)] px-[var(--gg-space-5)] text-[length:var(--gg-font-size-sm)] font-semibold text-[var(--gg-color-paper)] hover:bg-[var(--gg-color-deep)]"
+            >
+              Return home
+            </Link>
+          </div>
+        </Card>
+      </PageShell>
     </main>
   );
 }
diff --git a/apps/web/app/page.tsx b/apps/web/app/page.tsx
index df867ff..8426b1e 100644
--- a/apps/web/app/page.tsx
+++ b/apps/web/app/page.tsx
@@ -2,14 +2,19 @@ import Link from "next/link";
 
 import { searchGovernmentCatalog } from "@govgraph/domain";
 import { loadGovernmentCatalog, sourceRegistry } from "@govgraph/parsers";
-import { Badge, Card } from "@govgraph/ui";
+import {
+  Badge,
+  EmptyState,
+  NodeCard,
+  NodeTypeBadge,
+  PageShell,
+  SectionHeader,
+  SourceCard,
+  StatCard,
+} from "@govgraph/ui";
 
 import { SearchForm } from "./_components/search-form";
-import {
-  firstQueryValue,
-  humanizeNodeType,
-  humanizeSourceFamily,
-} from "./_lib/presenters";
+import { firstQueryValue, humanizeSourceFamily } from "./_lib/presenters";
 
 type HomePageProps = {
   searchParams: Promise<{ q?: string | string[] | undefined }>;
@@ -31,158 +36,132 @@ export default async function HomePage({ searchParams }: HomePageProps) {
   );
 
   return (
-    <main className="mx-auto flex min-h-screen w-full max-w-6xl flex-col gap-8 px-6 py-8 sm:px-8 lg:px-10 lg:py-12">
-      <section className="relative overflow-hidden rounded-[2.5rem] border border-[var(--govgraph-border)] bg-[linear-gradient(135deg,rgba(255,255,255,0.9),rgba(250,245,235,0.92))] p-6 shadow-[0_30px_90px_rgba(14,44,36,0.09)] backdrop-blur-sm sm:p-8 lg:p-10">
-        <div className="absolute -right-16 top-0 h-56 w-56 rounded-full bg-[radial-gradient(circle,rgba(185,74,55,0.22),rgba(185,74,55,0))]" />
-        <div className="absolute -left-8 bottom-0 h-40 w-40 rounded-full bg-[radial-gradient(circle,rgba(32,96,79,0.18),rgba(32,96,79,0))]" />
-        <div className="relative grid gap-8 lg:grid-cols-[1.2fr_0.8fr]">
-          <div className="space-y-6">
-            <div className="flex flex-wrap gap-3">
-              <Badge>Official source first</Badge>
-              <Badge>Sprint 2 underway</Badge>
+    <main>
+      <PageShell className="gap-[var(--gg-space-10)]">
+        <section className="relative overflow-hidden rounded-[var(--gg-radius-2xl)] border border-[var(--gg-color-border)] bg-[linear-gradient(135deg,rgba(255,255,255,0.9),rgba(250,245,235,0.92))] p-[var(--gg-space-6)] shadow-[var(--gg-shadow-lg)] backdrop-blur-sm sm:p-[var(--gg-space-8)] lg:p-[var(--gg-space-10)]">
+          <div className="absolute -right-16 top-0 h-56 w-56 rounded-full bg-[radial-gradient(circle,rgba(185,74,55,0.22),rgba(185,74,55,0))]" />
+          <div className="absolute -left-8 bottom-0 h-40 w-40 rounded-full bg-[radial-gradient(circle,rgba(32,96,79,0.18),rgba(32,96,79,0))]" />
+          <div className="relative grid gap-[var(--gg-space-8)] lg:grid-cols-[1.2fr_0.8fr]">
+            <div className="space-y-[var(--gg-space-6)]">
+              <div className="flex flex-wrap gap-[var(--gg-space-3)]">
+                <Badge tone="accent">Official source first</Badge>
+                <Badge tone="success">Sprint 2 underway</Badge>
+              </div>
+              <div className="space-y-[var(--gg-space-4)]">
+                <p className="text-[length:var(--gg-font-size-xs)] font-semibold uppercase tracking-[var(--gg-font-letter-spacing-eyebrow)] text-[var(--gg-color-semantic-text-secondary)]">
+                  Victorian Government Map
+                </p>
+                <h1 className="max-w-4xl font-[family-name:var(--gg-font-family-display)] text-[length:var(--gg-font-size-5xl)] font-semibold tracking-[var(--gg-font-letter-spacing-tight)] text-[var(--gg-color-ink)] sm:text-[length:var(--gg-font-size-6xl)]">
+                  Search the Victorian Government across structure, entities,
+                  and budget papers.
+                </h1>
+                <p className="max-w-3xl text-[length:var(--gg-font-size-base)] leading-[var(--gg-font-line-height-relaxed)] text-[var(--gg-color-semantic-text-secondary)] sm:text-[length:var(--gg-font-size-lg)]">
+                  The graph now combines the current ministry and portfolio map
+                  with the VPSC employers directory and the Victorian Budget
+                  paper index, plus structured budget outputs and performance
+                  measures, so public entities and budget records sit beside
+                  the core government structure.
+                </p>
+              </div>
+              <SearchForm
+                {...(query ? { defaultValue: query } : {})}
+                size="lg"
+              />
             </div>
-            <div className="space-y-4">
-              <p className="text-xs font-semibold uppercase tracking-[0.24em] text-[var(--govgraph-muted)]">
-                Victorian Government Map
-              </p>
-              <h1 className="max-w-4xl text-5xl font-semibold tracking-tight text-[var(--govgraph-ink)] sm:text-6xl">
-                Search the Victorian Government across structure, entities, and budget papers.
-              </h1>
-              <p className="max-w-3xl text-base leading-8 text-[var(--govgraph-muted)] sm:text-lg">
-                The graph now combines the current ministry and portfolio map
-                with the VPSC employers directory and the Victorian Budget paper
-                index, plus structured budget outputs and performance measures,
-                so public entities and budget records sit beside the core
-                government structure.
-              </p>
+
+            <div className="grid gap-[var(--gg-space-4)] sm:grid-cols-2 lg:grid-cols-2">
+              <StatCard
+                description="Records across ministers, departments, public entities, outputs, measures, and budget documents."
+                label="Live snapshot"
+                value={catalog.summary.totalNodes}
+              />
+              <StatCard
+                description="Live parsers feeding the search and node pages right now."
+                label="Connectors"
+                value={implementedConnectors.length}
+              />
+              <StatCard
+                description="Employer records pulled in from the live VPSC directory snapshot."
+                label="Public entities"
+                value={catalog.summary.countsByType.public_entity}
+              />
+              <StatCard
+                description="Indexed papers and budget tools now searchable from the same atlas."
+                label="Budget documents"
+                value={catalog.summary.countsByType.budget_document}
+              />
             </div>
-            <SearchForm {...(query ? { defaultValue: query } : {})} />
           </div>
+        </section>
 
-          <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-2">
-            <Card className="p-5">
-              <p className="text-xs font-semibold uppercase tracking-[0.18em] text-[var(--govgraph-muted)]">
-                Live snapshot
-              </p>
-              <p className="mt-4 text-4xl font-semibold text-[var(--govgraph-ink)]">
-                {catalog.summary.totalNodes}
-              </p>
-              <p className="mt-2 text-sm leading-6 text-[var(--govgraph-muted)]">
-                records across ministers, departments, public entities, outputs,
-                measures, and budget documents.
-              </p>
-            </Card>
-            <Card className="p-5">
-              <p className="text-xs font-semibold uppercase tracking-[0.18em] text-[var(--govgraph-muted)]">
-                Connectors
-              </p>
-              <p className="mt-4 text-4xl font-semibold text-[var(--govgraph-ink)]">
-                {implementedConnectors.length}
-              </p>
-              <p className="mt-2 text-sm leading-6 text-[var(--govgraph-muted)]">
-                live parsers feeding the search and node pages right now.
-              </p>
-            </Card>
-            <Card className="p-5">
-              <p className="text-xs font-semibold uppercase tracking-[0.18em] text-[var(--govgraph-muted)]">
-                Public entities
-              </p>
-              <p className="mt-4 text-4xl font-semibold text-[var(--govgraph-ink)]">
-                {catalog.summary.countsByType.public_entity}
-              </p>
-              <p className="mt-2 text-sm leading-6 text-[var(--govgraph-muted)]">
-                employer records pulled in from the live VPSC directory snapshot.
-              </p>
-            </Card>
-            <Card className="p-5">
-              <p className="text-xs font-semibold uppercase tracking-[0.18em] text-[var(--govgraph-muted)]">
-                Budget documents
-              </p>
-              <p className="mt-4 text-4xl font-semibold text-[var(--govgraph-ink)]">
-                {catalog.summary.countsByType.budget_document}
-              </p>
-              <p className="mt-2 text-sm leading-6 text-[var(--govgraph-muted)]">
-                indexed papers and budget tools now searchable from the same atlas.
-              </p>
-            </Card>
-          </div>
-        </div>
-      </section>
+        <section className="grid gap-[var(--gg-space-6)] lg:grid-cols-[1.2fr_0.8fr]">
+          <div className="space-y-[var(--gg-space-4)]">
+            <SectionHeader
+              eyebrow="Search results"
+              title={query ? `Results for “${query}”` : "Featured records"}
+              trailing={
+                query ? `${results.length} ${results.length === 1 ? "match" : "matches"}` : undefined
+              }
+            />
 
-      <section className="grid gap-6 lg:grid-cols-[1.2fr_0.8fr]">
-        <div className="space-y-4">
-          <div className="flex items-end justify-between gap-4">
-            <div>
-              <p className="text-xs font-semibold uppercase tracking-[0.2em] text-[var(--govgraph-muted)]">
-                Search results
-              </p>
-              <h2 className="mt-2 text-3xl font-semibold tracking-tight text-[var(--govgraph-ink)]">
-                {query ? `Results for “${query}”` : "Featured records"}
-              </h2>
+            <div className="grid gap-[var(--gg-space-4)]">
+              {query && results.length === 0 ? (
+                <EmptyState
+                  description="Try a minister title, a department name, a public entity name, or a budget paper keyword from the current Victorian Government data."
+                  title={`No live records match “${query}”`}
+                />
+              ) : (
+                (query ? results.map((result) => result.node) : featuredNodes).map(
+                  (node) => (
+                    <NodeCard
+                      key={node.id}
+                      badges={<NodeTypeBadge nodeType={node.nodeType} />}
+                      description={
+                        node.description ??
+                        "Current record in the live government graph snapshot."
+                      }
+                      title={
+                        <Link
+                          href={`/nodes/${node.slug}`}
+                          className="underline-offset-4 hover:underline"
+                        >
+                          {node.canonicalName}
+                        </Link>
+                      }
+                    />
+                  ),
+                )
+              )}
             </div>
-            {query ? (
-              <p className="text-sm text-[var(--govgraph-muted)]">
-                {results.length} matches
-              </p>
-            ) : null}
           </div>
 
-          <div className="grid gap-4">
-            {(query ? results.map((result) => result.node) : featuredNodes).map(
-              (node) => (
-                <Card
-                  key={node.id}
-                  className="p-5 transition-transform duration-200 hover:-translate-y-0.5"
-                >
-                  <div className="flex flex-wrap gap-3">
-                    <Badge>{humanizeNodeType(node.nodeType)}</Badge>
-                  </div>
-                  <Link
-                    href={`/nodes/${node.slug}`}
-                    className="mt-4 block text-2xl font-semibold tracking-tight text-[var(--govgraph-ink)] underline-offset-4 hover:underline"
-                  >
-                    {node.canonicalName}
-                  </Link>
-                  <p className="mt-2 text-sm leading-6 text-[var(--govgraph-muted)]">
-                    {node.description ??
-                      "Current record in the live government graph snapshot."}
-                  </p>
-                </Card>
-              ),
-            )}
-          </div>
-        </div>
-
-        <div className="space-y-4">
-          <div>
-            <p className="text-xs font-semibold uppercase tracking-[0.2em] text-[var(--govgraph-muted)]">
-              Source registry
-            </p>
-            <h2 className="mt-2 text-3xl font-semibold tracking-tight text-[var(--govgraph-ink)]">
-              Current connectors
-            </h2>
-          </div>
-          <div className="grid gap-4">
-            {sourceRegistry.map((entry) => (
-              <Card key={entry.id} className="p-5">
-                <div className="flex flex-wrap gap-3">
-                  <Badge>{humanizeSourceFamily(entry.sourceFamily)}</Badge>
-                  <Badge>{entry.implementationStatus}</Badge>
-                </div>
-                <h3 className="mt-4 text-xl font-semibold text-[var(--govgraph-ink)]">
-                  {entry.name}
-                </h3>
-                <p className="mt-2 text-sm leading-6 text-[var(--govgraph-muted)]">
-                  {entry.description}
-                </p>
-                <p className="mt-3 text-xs font-semibold uppercase tracking-[0.18em] text-[var(--govgraph-muted)]">
-                  {entry.cadence}
-                </p>
-              </Card>
-            ))}
+          <div className="space-y-[var(--gg-space-4)]">
+            <SectionHeader
+              eyebrow="Source registry"
+              title="Current connectors"
+              description="Every live parser feeding the atlas, shown with its source family, cadence, and current implementation status."
+            />
+            <div className="grid gap-[var(--gg-space-4)]">
+              {sourceRegistry.map((entry) => (
+                <SourceCard
+                  key={entry.id}
+                  badges={
+                    <>
+                      <Badge>{humanizeSourceFamily(entry.sourceFamily)}</Badge>
+                      <Badge tone={entry.implementationStatus === "implemented" ? "success" : "muted"}>
+                        {entry.implementationStatus}
+                      </Badge>
+                    </>
+                  }
+                  description={entry.description}
+                  metadata={entry.cadence}
+                  title={entry.name}
+                />
+              ))}
+            </div>
           </div>
-        </div>
-      </section>
+        </section>
+      </PageShell>
     </main>
   );
 }
diff --git a/docs/design-system.md b/docs/design-system.md
new file mode 100644
index 0000000..a53dce9
--- /dev/null
+++ b/docs/design-system.md
@@ -0,0 +1,25 @@
+# GovGraph Design System
+
+GovGraph now uses a shared design system built around typed tokens in `packages/ui/src/tokens`. Those tokens generate the CSS custom properties consumed by the app and the shared UI components.
+
+## What To Use
+
+- Start page work with `PageShell`, then add `SectionHeader` for major sections.
+- Use `NodeCard`, `SourceCard`, and `StatCard` for the atlas views before creating new one-off layouts.
+- Use `NodeTypeBadge` for node categories and `Badge` for status or metadata labels.
+- Use `KeyValue`, `MetricBar`, `DataTable`, and `TimelineEntry` for structured factual content.
+- Use `EmptyState` and `Skeleton` for quiet states instead of raw text placeholders.
+
+## Token Rules
+
+- Prefer `--gg-*` variables for all new work.
+- Treat `--govgraph-*` variables as migration aliases only.
+- Keep tokens authored in TypeScript and regenerate `packages/ui/src/tokens/generated.css` after changes.
+- Do not hardcode palette values inside pages or components when a token already exists.
+
+## Working Style
+
+- Keep shared components small and composable.
+- Keep page-specific flourishes, like the homepage hero treatment, inside the app.
+- Avoid gradients in component defaults. If a page needs a more expressive surface, keep that styling local to the page.
+- Check new patterns on `/design` before using them in live routes.
diff --git a/packages/ui/package.json b/packages/ui/package.json
index 91d5d95..cbe180e 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -4,22 +4,28 @@
   "version": "0.1.0",
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./tokens": "./src/tokens/index.ts",
+    "./tokens.css": "./src/tokens/generated.css"
   },
   "types": "./src/index.ts",
   "scripts": {
     "build": "tsc --noEmit",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "generate:tokens": "pnpm exec tsx scripts/generate-token-css.ts"
   },
   "dependencies": {
     "clsx": "^2.1.1",
     "tailwind-merge": "^3.3.1"
   },
   "devDependencies": {
+    "@types/node": "^24.12.2",
     "@types/react": "^19.2.2",
     "@types/react-dom": "^19.2.2",
     "react": "^19.2.0",
-    "react-dom": "^19.2.0"
+    "react-dom": "^19.2.0",
+    "vitest": "^3.2.4"
   },
   "peerDependencies": {
     "react": "^19.2.0",
diff --git a/packages/ui/scripts/generate-token-css.ts b/packages/ui/scripts/generate-token-css.ts
new file mode 100644
index 0000000..5d92f65
--- /dev/null
+++ b/packages/ui/scripts/generate-token-css.ts
@@ -0,0 +1,10 @@
+import { writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { buildGovGraphTokenCss } from "../src/tokens";
+
+const currentDirectory = dirname(fileURLToPath(import.meta.url));
+const outputPath = resolve(currentDirectory, "../src/tokens/generated.css");
+
+writeFileSync(outputPath, `${buildGovGraphTokenCss()}\n`);
diff --git a/packages/ui/src/badge.tsx b/packages/ui/src/badge.tsx
index 2842b61..3727e38 100644
--- a/packages/ui/src/badge.tsx
+++ b/packages/ui/src/badge.tsx
@@ -2,11 +2,37 @@ import type { HTMLAttributes } from "react";
 
 import { cn } from "./utils";
 
-export function Badge({ className, ...props }: HTMLAttributes<HTMLSpanElement>) {
+const toneClasses = {
+  neutral:
+    "border-[var(--gg-color-border)] bg-[var(--gg-color-wash)] text-[var(--gg-color-semantic-text-secondary)]",
+  muted:
+    "border-[var(--gg-color-border)] bg-[var(--gg-color-semantic-surface-muted)] text-[var(--gg-color-semantic-text-secondary)]",
+  accent:
+    "border-[color:rgba(185,74,55,0.24)] bg-[color:rgba(185,74,55,0.12)] text-[var(--gg-color-accent)]",
+  success:
+    "border-[color:rgba(47,107,87,0.24)] bg-[color:rgba(47,107,87,0.12)] text-[var(--gg-color-semantic-success)]",
+  warning:
+    "border-[color:rgba(138,104,33,0.24)] bg-[color:rgba(138,104,33,0.14)] text-[var(--gg-color-semantic-warning)]",
+  danger:
+    "border-[color:rgba(159,63,50,0.24)] bg-[color:rgba(159,63,50,0.12)] text-[var(--gg-color-semantic-danger)]",
+} as const;
+
+export type BadgeTone = keyof typeof toneClasses;
+
+type BadgeProps = HTMLAttributes<HTMLSpanElement> & {
+  tone?: BadgeTone;
+};
+
+export function Badge({
+  className,
+  tone = "neutral",
+  ...props
+}: BadgeProps) {
   return (
     <span
       className={cn(
-        "inline-flex items-center rounded-full border border-[var(--govgraph-border)] bg-[var(--govgraph-wash)] px-3 py-1 text-xs font-medium uppercase tracking-[0.18em] text-[var(--govgraph-muted)]",
+        "inline-flex items-center rounded-[var(--gg-radius-full)] border px-[var(--gg-space-3)] py-[var(--gg-space-1)] text-[length:var(--gg-font-size-xs)] font-medium uppercase tracking-[var(--gg-font-letter-spacing-caps)]",
+        toneClasses[tone],
         className,
       )}
       {...props}
diff --git a/packages/ui/src/breadcrumb.tsx b/packages/ui/src/breadcrumb.tsx
new file mode 100644
index 0000000..0127eb9
--- /dev/null
+++ b/packages/ui/src/breadcrumb.tsx
@@ -0,0 +1,45 @@
+import type { HTMLAttributes, ReactNode } from "react";
+
+import { cn } from "./utils";
+
+export type BreadcrumbItem = {
+  content: ReactNode;
+  current?: boolean;
+};
+
+type BreadcrumbProps = HTMLAttributes<HTMLElement> & {
+  items: readonly BreadcrumbItem[];
+};
+
+export function Breadcrumb({
+  className,
+  items,
+  ...props
+}: BreadcrumbProps) {
+  return (
+    <nav
+      aria-label="Breadcrumb"
+      className={cn(
+        "flex flex-wrap items-center gap-[var(--gg-space-2)] text-[length:var(--gg-font-size-sm)] text-[var(--gg-color-semantic-text-secondary)]",
+        className,
+      )}
+      {...props}
+    >
+      {items.map((item, index) => (
+        <span key={`${index}-${item.current ? "current" : "link"}`} className="inline-flex items-center gap-[var(--gg-space-2)]">
+          {index > 0 ? (
+            <span aria-hidden="true" className="text-[var(--gg-color-muted)]">
+              /
+            </span>
+          ) : null}
+          <span
+            aria-current={item.current ? "page" : undefined}
+            className={cn(item.current ? "font-semibold text-[var(--gg-color-ink)]" : "underline-offset-4 hover:text-[var(--gg-color-deep)] hover:underline")}
+          >
+            {item.content}
+          </span>
+        </span>
+      ))}
+    </nav>
+  );
+}
diff --git a/packages/ui/src/button.tsx b/packages/ui/src/button.tsx
index fff25e0..5f7f7e7 100644
--- a/packages/ui/src/button.tsx
+++ b/packages/ui/src/button.tsx
@@ -2,19 +2,39 @@ import type { ButtonHTMLAttributes, ReactNode } from "react";
 
 import { cn } from "./utils";
 
+const toneClasses = {
+  primary:
+    "border-[var(--gg-color-ink)] bg-[var(--gg-color-ink)] text-[var(--gg-color-paper)] hover:bg-[var(--gg-color-deep)]",
+  ghost:
+    "border-[var(--gg-color-border)] bg-transparent text-[var(--gg-color-ink)] hover:bg-[color:rgba(14,44,36,0.06)]",
+  danger:
+    "border-[var(--gg-color-semantic-danger)] bg-[var(--gg-color-semantic-danger)] text-[var(--gg-color-paper)] hover:bg-[color:#7f3127]",
+} as const;
+
+const sizeClasses = {
+  sm: "min-h-[2.5rem] px-[var(--gg-space-4)] text-[length:var(--gg-font-size-sm)]",
+  md: "min-h-[2.9rem] px-[var(--gg-space-5)] text-[length:var(--gg-font-size-sm)]",
+  lg: "min-h-[3.4rem] px-[var(--gg-space-6)] text-[length:var(--gg-font-size-base)]",
+} as const;
+
 type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
   children: ReactNode;
-  tone?: "primary" | "ghost";
+  size?: keyof typeof sizeClasses;
+  tone?: keyof typeof toneClasses;
 };
 
-export function Button({ className, tone = "primary", ...props }: ButtonProps) {
+export function Button({
+  className,
+  size = "md",
+  tone = "primary",
+  ...props
+}: ButtonProps) {
   return (
     <button
       className={cn(
-        "inline-flex items-center justify-center rounded-full border px-4 py-2 text-sm font-semibold transition duration-150 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2",
-        tone === "primary"
-          ? "border-[var(--govgraph-ink)] bg-[var(--govgraph-ink)] text-[var(--govgraph-paper)] hover:bg-[var(--govgraph-deep)]"
-          : "border-[var(--govgraph-border)] bg-transparent text-[var(--govgraph-ink)] hover:bg-[color:rgba(14,44,36,0.06)]",
+        "inline-flex items-center justify-center rounded-[var(--gg-radius-full)] border font-semibold transition-[color,background-color,border-color,transform,box-shadow] duration-[var(--gg-animation-duration-normal)] ease-[var(--gg-animation-easing-standard)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--gg-color-semantic-focus-ring)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--gg-color-paper)] disabled:cursor-not-allowed disabled:opacity-60",
+        sizeClasses[size],
+        toneClasses[tone],
         className,
       )}
       {...props}
diff --git a/packages/ui/src/card.tsx b/packages/ui/src/card.tsx
index b77c951..f0315fe 100644
--- a/packages/ui/src/card.tsx
+++ b/packages/ui/src/card.tsx
@@ -2,11 +2,28 @@ import type { HTMLAttributes } from "react";
 
 import { cn } from "./utils";
 
-export function Card({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+const toneClasses = {
+  default:
+    "bg-[var(--gg-color-semantic-surface-strong)] shadow-[var(--gg-shadow-md)]",
+  muted:
+    "bg-[var(--gg-color-semantic-surface)] shadow-[var(--gg-shadow-sm)]",
+  hero: "bg-[var(--gg-color-paper-strong)] shadow-[var(--gg-shadow-lg)]",
+} as const;
+
+type CardProps = HTMLAttributes<HTMLDivElement> & {
+  tone?: keyof typeof toneClasses;
+};
+
+export function Card({
+  className,
+  tone = "default",
+  ...props
+}: CardProps) {
   return (
     <div
       className={cn(
-        "rounded-[1.75rem] border border-[var(--govgraph-border)] bg-white/90 shadow-[0_18px_48px_rgba(14,44,36,0.08)] backdrop-blur-sm",
+        "rounded-[var(--gg-radius-lg)] border border-[var(--gg-color-border)] backdrop-blur-sm",
+        toneClasses[tone],
         className,
       )}
       {...props}
diff --git a/packages/ui/src/data-table-sort.test.ts b/packages/ui/src/data-table-sort.test.ts
new file mode 100644
index 0000000..dabeee7
--- /dev/null
+++ b/packages/ui/src/data-table-sort.test.ts
@@ -0,0 +1,55 @@
+import { formatCellValue, sortRows } from "./data-table-sort";
+
+const rows = [
+  {
+    agency: "Transport and Planning",
+    budget: 16_700_000_000,
+    workforce: 3940,
+  },
+  {
+    agency: "Treasury and Finance",
+    budget: 8_300_000_000,
+    workforce: 1450,
+  },
+  {
+    agency: "Education",
+    budget: null,
+    workforce: 2180,
+  },
+] as const;
+
+describe("sortRows", () => {
+  it("sorts ascending while keeping nulls at the end", () => {
+    const sorted = sortRows(rows, {
+      columnKey: "budget",
+      direction: "asc",
+    });
+
+    expect(sorted.map((row) => row.agency)).toEqual([
+      "Treasury and Finance",
+      "Transport and Planning",
+      "Education",
+    ]);
+  });
+
+  it("sorts descending for numeric columns", () => {
+    const sorted = sortRows(rows, {
+      columnKey: "workforce",
+      direction: "desc",
+    });
+
+    expect(sorted.map((row) => row.agency)).toEqual([
+      "Transport and Planning",
+      "Education",
+      "Treasury and Finance",
+    ]);
+  });
+});
+
+describe("formatCellValue", () => {
+  it("formats numbers for table display", () => {
+    expect(formatCellValue(1450, "number")).toBe("1,450");
+    expect(formatCellValue(8300000000, "currency")).toBe("$8,300,000,000");
+    expect(formatCellValue(null, "text")).toBe("—");
+  });
+});
diff --git a/packages/ui/src/data-table-sort.ts b/packages/ui/src/data-table-sort.ts
new file mode 100644
index 0000000..af6063a
--- /dev/null
+++ b/packages/ui/src/data-table-sort.ts
@@ -0,0 +1,80 @@
+export type DataTableValue = number | string | null;
+
+export type DataTableRow = Record<string, DataTableValue>;
+
+export type DataTableColumn<Row extends DataTableRow> = {
+  align?: "left" | "right";
+  format?: "currency" | "number" | "text";
+  header: string;
+  key: keyof Row & string;
+  sortable?: boolean;
+};
+
+export type DataTableSortState<Row extends DataTableRow> = {
+  columnKey: keyof Row & string;
+  direction: "asc" | "desc";
+} | null;
+
+function compareValues(left: DataTableValue, right: DataTableValue): number {
+  if (left === right) {
+    return 0;
+  }
+
+  if (left === null) {
+    return 1;
+  }
+
+  if (right === null) {
+    return -1;
+  }
+
+  if (typeof left === "number" && typeof right === "number") {
+    return left - right;
+  }
+
+  return String(left).localeCompare(String(right), undefined, {
+    numeric: true,
+    sensitivity: "base",
+  });
+}
+
+export function sortRows<Row extends DataTableRow>(
+  rows: readonly Row[],
+  sortState: DataTableSortState<Row>,
+): Row[] {
+  if (!sortState) {
+    return [...rows];
+  }
+
+  return [...rows].sort((left, right) => {
+    const result = compareValues(
+      left[sortState.columnKey] ?? null,
+      right[sortState.columnKey] ?? null,
+    );
+
+    return sortState.direction === "asc" ? result : -result;
+  });
+}
+
+export function formatCellValue(
+  value: DataTableValue,
+  format: DataTableColumn<DataTableRow>["format"],
+): string {
+  if (value === null) {
+    return "—";
+  }
+
+  if (format === "currency" && typeof value === "number") {
+    return new Intl.NumberFormat("en-AU", {
+      style: "currency",
+      currency: "AUD",
+      maximumFractionDigits: 0,
+    }).format(value);
+  }
+
+  if (format === "number" && typeof value === "number") {
+    return value.toLocaleString("en-AU");
+  }
+
+  return String(value);
+}
diff --git a/packages/ui/src/data-table.tsx b/packages/ui/src/data-table.tsx
new file mode 100644
index 0000000..f02de03
--- /dev/null
+++ b/packages/ui/src/data-table.tsx
@@ -0,0 +1,141 @@
+"use client";
+
+import type { HTMLAttributes } from "react";
+import { useState } from "react";
+
+import {
+  formatCellValue,
+  sortRows,
+  type DataTableColumn,
+  type DataTableRow,
+  type DataTableSortState,
+} from "./data-table-sort";
+import { cn } from "./utils";
+
+type DataTableProps<Row extends DataTableRow> = HTMLAttributes<HTMLDivElement> & {
+  caption?: string;
+  columns: readonly DataTableColumn<Row>[];
+  emptyMessage?: string;
+  rows: readonly Row[];
+};
+
+function nextSortDirection<Row extends DataTableRow>(
+  current: DataTableSortState<Row>,
+  columnKey: keyof Row & string,
+): DataTableSortState<Row> {
+  if (!current || current.columnKey !== columnKey) {
+    return { columnKey, direction: "asc" };
+  }
+
+  if (current.direction === "asc") {
+    return { columnKey, direction: "desc" };
+  }
+
+  return null;
+}
+
+export function DataTable<Row extends DataTableRow>({
+  caption,
+  className,
+  columns,
+  emptyMessage = "No rows to display.",
+  rows,
+  ...props
+}: DataTableProps<Row>) {
+  const [sortState, setSortState] = useState<DataTableSortState<Row>>(null);
+  const sortedRows = sortRows(rows, sortState);
+
+  return (
+    <div
+      className={cn(
+        "overflow-hidden rounded-[var(--gg-radius-lg)] border border-[var(--gg-color-border)] bg-[var(--gg-color-semantic-surface-strong)] shadow-[var(--gg-shadow-sm)]",
+        className,
+      )}
+      {...props}
+    >
+      <table className="min-w-full border-collapse">
+        {caption ? (
+          <caption className="sr-only">{caption}</caption>
+        ) : null}
+        <thead className="bg-[var(--gg-color-semantic-surface-muted)]">
+          <tr>
+            {columns.map((column) => {
+              const isSorted = sortState?.columnKey === column.key;
+              const indicator = !column.sortable
+                ? null
+                : isSorted
+                  ? sortState?.direction === "asc"
+                    ? "ASC"
+                    : "DESC"
+                  : "SORT";
+
+              return (
+                <th
+                  key={column.key}
+                  className={cn(
+                    "px-[var(--gg-space-4)] py-[var(--gg-space-3)] text-left text-[length:var(--gg-font-size-xs)] font-semibold uppercase tracking-[var(--gg-font-letter-spacing-caps)] text-[var(--gg-color-semantic-text-secondary)]",
+                    column.align === "right" ? "text-right" : undefined,
+                  )}
+                  scope="col"
+                >
+                  {column.sortable ? (
+                    <button
+                      className={cn(
+                        "inline-flex items-center gap-[var(--gg-space-2)] underline-offset-4 hover:text-[var(--gg-color-deep)] hover:underline",
+                        column.align === "right" ? "ml-auto" : undefined,
+                      )}
+                      onClick={() =>
+                        setSortState((current) =>
+                          nextSortDirection(current, column.key),
+                        )
+                      }
+                      type="button"
+                    >
+                      <span>{column.header}</span>
+                      {indicator ? (
+                        <span className="text-[10px]">{indicator}</span>
+                      ) : null}
+                    </button>
+                  ) : (
+                    column.header
+                  )}
+                </th>
+              );
+            })}
+          </tr>
+        </thead>
+        <tbody>
+          {sortedRows.length === 0 ? (
+            <tr>
+              <td
+                className="px-[var(--gg-space-4)] py-[var(--gg-space-6)] text-[length:var(--gg-font-size-sm)] text-[var(--gg-color-semantic-text-secondary)]"
+                colSpan={columns.length}
+              >
+                {emptyMessage}
+              </td>
+            </tr>
+          ) : (
+            sortedRows.map((row, rowIndex) => (
+              <tr
+                key={rowIndex}
+                className="border-t border-[var(--gg-color-border)] first:border-t-0"
+              >
+                {columns.map((column) => (
+                  <td
+                    key={column.key}
+                    className={cn(
+                      "px-[var(--gg-space-4)] py-[var(--gg-space-4)] text-[length:var(--gg-font-size-sm)] leading-[var(--gg-font-line-height-body)] text-[var(--gg-color-ink)]",
+                      column.align === "right" ? "text-right" : undefined,
+                    )}
+                  >
+                    {formatCellValue(row[column.key] ?? null, column.format)}
+                  </td>
+                ))}
+              </tr>
+            ))
+          )}
+        </tbody>
+      </table>
+    </div>
+  );
+}
diff --git a/packages/ui/src/empty-state.tsx b/packages/ui/src/empty-state.tsx
new file mode 100644
index 0000000..18b4605
--- /dev/null
+++ b/packages/ui/src/empty-state.tsx
@@ -0,0 +1,41 @@
+import type { HTMLAttributes, ReactNode } from "react";
+
+import { Card } from "./card";
+import { cn } from "./utils";
+
+type EmptyStateProps = Omit<HTMLAttributes<HTMLDivElement>, "title"> & {
+  action?: ReactNode;
+  description: ReactNode;
+  title: ReactNode;
+};
+
+export function EmptyState({
+  action,
+  className,
+  description,
+  title,
+  ...props
+}: EmptyStateProps) {
+  return (
+    <Card
+      className={cn(
+        "flex flex-col items-center justify-center gap-[var(--gg-space-4)] px-[var(--gg-space-6)] py-[var(--gg-space-8)] text-center",
+        className,
+      )}
+      {...props}
+    >
+      <div className="relative flex h-16 w-16 items-center justify-center rounded-[var(--gg-radius-full)] border border-[var(--gg-color-border)] bg-[var(--gg-color-semantic-surface-muted)]">
+        <div className="h-7 w-7 rounded-[var(--gg-radius-full)] border border-[color:rgba(185,74,55,0.4)] bg-[color:rgba(185,74,55,0.12)]" />
+      </div>
+      <div className="space-y-[var(--gg-space-2)]">
+        <h3 className="font-[family-name:var(--gg-font-family-display)] text-[length:var(--gg-font-size-2xl)] font-semibold tracking-[var(--gg-font-letter-spacing-tight)] text-[var(--gg-color-ink)]">
+          {title}
+        </h3>
+        <p className="max-w-xl text-[length:var(--gg-font-size-sm)] leading-[var(--gg-font-line-height-body)] text-[var(--gg-color-semantic-text-secondary)]">
+          {description}
+        </p>
+      </div>
+      {action ? <div>{action}</div> : null}
+    </Card>
+  );
+}
diff --git a/packages/ui/src/footer.tsx b/packages/ui/src/footer.tsx
new file mode 100644
index 0000000..b52b02e
--- /dev/null
+++ b/packages/ui/src/footer.tsx
@@ -0,0 +1,42 @@
+import type { HTMLAttributes, ReactNode } from "react";
+
+import { cn } from "./utils";
+
+type FooterProps = HTMLAttributes<HTMLElement> & {
+  summary: ReactNode;
+  links?: ReactNode;
+  meta?: ReactNode;
+};
+
+export function Footer({
+  className,
+  summary,
+  links,
+  meta,
+  ...props
+}: FooterProps) {
+  return (
+    <footer
+      className={cn(
+        "border-t border-[var(--gg-color-border)] bg-[color:rgba(255,250,241,0.7)]",
+        className,
+      )}
+      {...props}
+    >
+      <div className="mx-auto grid w-full max-w-6xl gap-[var(--gg-space-6)] px-[var(--gg-space-6)] py-[var(--gg-space-8)] sm:px-[var(--gg-space-8)] lg:grid-cols-[1.2fr_0.8fr] lg:px-[var(--gg-space-10)]">
+        <div className="space-y-[var(--gg-space-3)]">
+          <p className="font-[family-name:var(--gg-font-family-display)] text-[length:var(--gg-font-size-2xl)] font-semibold tracking-[var(--gg-font-letter-spacing-tight)] text-[var(--gg-color-ink)]">
+            GovGraph
+          </p>
+          <div className="max-w-2xl text-[length:var(--gg-font-size-sm)] leading-[var(--gg-font-line-height-body)] text-[var(--gg-color-semantic-text-secondary)]">
+            {summary}
+          </div>
+        </div>
+        <div className="space-y-[var(--gg-space-3)] text-[length:var(--gg-font-size-sm)] text-[var(--gg-color-semantic-text-secondary)]">
+          {links}
+          {meta ? <div>{meta}</div> : null}
+        </div>
+      </div>
+    </footer>
+  );
+}
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 0e09cec..71d772f 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -1,5 +1,24 @@
 export * from "./badge";
+export * from "./breadcrumb";
 export * from "./button";
 export * from "./card";
+export * from "./data-table";
+export * from "./data-table-sort";
+export * from "./empty-state";
+export * from "./footer";
 export * from "./input";
+export * from "./key-value";
+export * from "./metric-bar";
+export * from "./node-card";
+export * from "./node-type-badge";
+export * from "./page-shell";
+export * from "./section-header";
+export * from "./site-header";
+export * from "./skeleton";
+export * from "./source-card";
+export * from "./stat-card";
+export * from "./textarea";
+export * from "./timeline-entry";
+export * from "./tokens";
+export * from "./tooltip";
 export * from "./utils";
diff --git a/packages/ui/src/input.tsx b/packages/ui/src/input.tsx
index a26abf3..7d857e4 100644
--- a/packages/ui/src/input.tsx
+++ b/packages/ui/src/input.tsx
@@ -6,7 +6,7 @@ export function Input({ className, ...props }: InputHTMLAttributes<HTMLInputElem
   return (
     <input
       className={cn(
-        "w-full rounded-full border border-[var(--govgraph-border)] bg-white/90 px-5 py-3 text-base text-[var(--govgraph-ink)] shadow-sm outline-none transition duration-150 placeholder:text-[var(--govgraph-muted)] focus:border-[var(--govgraph-ink)] focus:ring-2 focus:ring-[color:rgba(14,44,36,0.12)]",
+        "w-full rounded-[var(--gg-radius-full)] border border-[var(--gg-color-border)] bg-[var(--gg-color-semantic-surface-strong)] px-[var(--gg-space-5)] py-[var(--gg-space-3)] text-[length:var(--gg-font-size-base)] text-[var(--gg-color-ink)] shadow-[var(--gg-shadow-sm)] outline-none transition-[color,background-color,border-color,box-shadow] duration-[var(--gg-animation-duration-normal)] ease-[var(--gg-animation-easing-standard)] placeholder:text-[var(--gg-color-muted)] focus:border-[var(--gg-color-deep)] focus:ring-2 focus:ring-[var(--gg-color-semantic-focus-ring)]",
         className,
       )}
       {...props}
diff --git a/packages/ui/src/key-value.tsx b/packages/ui/src/key-value.tsx
new file mode 100644
index 0000000..cf070b0
--- /dev/null
+++ b/packages/ui/src/key-value.tsx
@@ -0,0 +1,32 @@
+import type { HTMLAttributes, ReactNode } from "react";
+
+import { cn } from "./utils";
+
+type KeyValueProps = HTMLAttributes<HTMLDivElement> & {
+  label: ReactNode;
+  value: ReactNode;
+};
+
+export function KeyValue({
+  className,
+  label,
+  value,
+  ...props
+}: KeyValueProps) {
+  return (
+    <div
+      className={cn(
+        "grid grid-cols-[minmax(0,0.9fr)_minmax(0,1.1fr)] gap-[var(--gg-space-3)] border-b border-[var(--gg-color-border)] py-[var(--gg-space-3)] last:border-b-0 last:pb-0 first:pt-0",
+        className,
+      )}
+      {...props}
+    >
+      <dt className="text-[length:var(--gg-font-size-xs)] font-semibold uppercase tracking-[var(--gg-font-letter-spacing-caps)] text-[var(--gg-color-semantic-text-secondary)]">
+        {label}
+      </dt>
+      <dd className="text-[length:var(--gg-font-size-sm)] leading-[var(--gg-font-line-height-body)] text-[var(--gg-color-ink)]">
+        {value}
+      </dd>
+    </div>
+  );
+}
diff --git a/packages/ui/src/metric-bar.tsx b/packages/ui/src/metric-bar.tsx
new file mode 100644
index 0000000..303e2af
--- /dev/null
+++ b/packages/ui/src/metric-bar.tsx
@@ -0,0 +1,58 @@
+import type { HTMLAttributes, ReactNode } from "react";
+
+import { cn } from "./utils";
+
+type MetricBarProps = HTMLAttributes<HTMLDivElement> & {
+  detail?: ReactNode;
+  label: ReactNode;
+  max: number;
+  tone?: "accent" | "deep" | "muted";
+  value: number;
+  valueLabel?: ReactNode;
+};
+
+const barToneClasses = {
+  accent: "bg-[var(--gg-color-accent)]",
+  deep: "bg-[var(--gg-color-deep)]",
+  muted: "bg-[var(--gg-color-muted)]",
+} as const;
+
+export function MetricBar({
+  className,
+  detail,
+  label,
+  max,
+  tone = "accent",
+  value,
+  valueLabel,
+  ...props
+}: MetricBarProps) {
+  const percentage = max <= 0 ? 0 : Math.min((value / max) * 100, 100);
+
+  return (
+    <div className={cn("space-y-[var(--gg-space-2)]", className)} {...props}>
+      <div className="flex items-center justify-between gap-[var(--gg-space-3)]">
+        <p className="text-[length:var(--gg-font-size-sm)] font-medium text-[var(--gg-color-ink)]">
+          {label}
+        </p>
+        <p className="text-[length:var(--gg-font-size-sm)] text-[var(--gg-color-semantic-text-secondary)]">
+          {valueLabel ?? value.toLocaleString()}
+        </p>
+      </div>
+      <div className="h-[0.75rem] overflow-hidden rounded-[var(--gg-radius-full)] bg-[var(--gg-color-wash)]">
+        <div
+          className={cn(
+            "h-full rounded-[var(--gg-radius-full)] transition-[width] duration-[var(--gg-animation-duration-slow)] ease-[var(--gg-animation-easing-standard)]",
+            barToneClasses[tone],
+          )}
+          style={{ width: `${percentage}%` }}
+        />
+      </div>
+      {detail ? (
+        <p className="text-[length:var(--gg-font-size-xs)] leading-[var(--gg-font-line-height-body)] text-[var(--gg-color-semantic-text-secondary)]">
+          {detail}
+        </p>
+      ) : null}
+    </div>
+  );
+}
diff --git a/packages/ui/src/node-card.tsx b/packages/ui/src/node-card.tsx
new file mode 100644
index 0000000..0510a69
--- /dev/null
+++ b/packages/ui/src/node-card.tsx
@@ -0,0 +1,43 @@
+import type { HTMLAttributes, ReactNode } from "react";
+
+import { Card } from "./card";
+import { cn } from "./utils";
+
+type NodeCardProps = Omit<HTMLAttributes<HTMLDivElement>, "title"> & {
+  badges?: ReactNode;
+  description?: ReactNode;
+  footer?: ReactNode;
+  title: ReactNode;
+};
+
+export function NodeCard({
+  badges,
+  className,
+  description,
+  footer,
+  title,
+  ...props
+}: NodeCardProps) {
+  return (
+    <Card
+      className={cn(
+        "p-[var(--gg-space-5)] transition-transform duration-[var(--gg-animation-duration-slow)] ease-[var(--gg-animation-easing-standard)] hover:-translate-y-0.5",
+        className,
+      )}
+      {...props}
+    >
+      {badges ? <div className="flex flex-wrap gap-[var(--gg-space-3)]">{badges}</div> : null}
+      <div className="mt-[var(--gg-space-4)] space-y-[var(--gg-space-2)]">
+        <div className="font-[family-name:var(--gg-font-family-display)] text-[length:var(--gg-font-size-2xl)] font-semibold tracking-[var(--gg-font-letter-spacing-tight)] text-[var(--gg-color-ink)]">
+          {title}
+        </div>
+        {description ? (
+          <p className="text-[length:var(--gg-font-size-sm)] leading-[var(--gg-font-line-height-body)] text-[var(--gg-color-semantic-text-secondary)]">
+            {description}
+          </p>
+        ) : null}
+      </div>
+      {footer ? <div className="mt-[var(--gg-space-4)]">{footer}</div> : null}
+    </Card>
+  );
+}
diff --git a/packages/ui/src/node-type-badge.tsx b/packages/ui/src/node-type-badge.tsx
new file mode 100644
index 0000000..f8b0618
--- /dev/null
+++ b/packages/ui/src/node-type-badge.tsx
@@ -0,0 +1,62 @@
+import type { HTMLAttributes } from "react";
+
+import { Badge } from "./badge";
+import { cn } from "./utils";
+
+const nodeTypeToneClasses = {
+  person:
+    "border-[var(--gg-color-node-person-border)] bg-[var(--gg-color-node-person-bg)] text-[var(--gg-color-node-person-text)]",
+  ministry:
+    "border-[var(--gg-color-node-ministry-border)] bg-[var(--gg-color-node-ministry-bg)] text-[var(--gg-color-node-ministry-text)]",
+  portfolio:
+    "border-[var(--gg-color-node-portfolio-border)] bg-[var(--gg-color-node-portfolio-bg)] text-[var(--gg-color-node-portfolio-text)]",
+  department:
+    "border-[var(--gg-color-node-department-border)] bg-[var(--gg-color-node-department-bg)] text-[var(--gg-color-node-department-text)]",
+  administrative_office:
+    "border-[var(--gg-color-node-administrative-office-border)] bg-[var(--gg-color-node-administrative-office-bg)] text-[var(--gg-color-node-administrative-office-text)]",
+  public_entity:
+    "border-[var(--gg-color-node-public-entity-border)] bg-[var(--gg-color-node-public-entity-bg)] text-[var(--gg-color-node-public-entity-text)]",
+  program_output:
+    "border-[var(--gg-color-node-program-output-border)] bg-[var(--gg-color-node-program-output-bg)] text-[var(--gg-color-node-program-output-text)]",
+  capital_project:
+    "border-[var(--gg-color-node-capital-project-border)] bg-[var(--gg-color-node-capital-project-bg)] text-[var(--gg-color-node-capital-project-text)]",
+  performance_measure:
+    "border-[var(--gg-color-node-performance-measure-border)] bg-[var(--gg-color-node-performance-measure-bg)] text-[var(--gg-color-node-performance-measure-text)]",
+  budget_document:
+    "border-[var(--gg-color-node-budget-document-border)] bg-[var(--gg-color-node-budget-document-bg)] text-[var(--gg-color-node-budget-document-text)]",
+  source_document:
+    "border-[var(--gg-color-node-source-document-border)] bg-[var(--gg-color-node-source-document-bg)] text-[var(--gg-color-node-source-document-text)]",
+  organisation_group:
+    "border-[var(--gg-color-node-organisation-group-border)] bg-[var(--gg-color-node-organisation-group-bg)] text-[var(--gg-color-node-organisation-group-text)]",
+} as const;
+
+export type NodeTypeBadgeType = keyof typeof nodeTypeToneClasses;
+
+function humanizeNodeType(nodeType: NodeTypeBadgeType): string {
+  return nodeType.replace(/_/g, " ");
+}
+
+export function getNodeTypeBadgeClasses(nodeType: NodeTypeBadgeType): string {
+  return nodeTypeToneClasses[nodeType];
+}
+
+type NodeTypeBadgeProps = HTMLAttributes<HTMLSpanElement> & {
+  label?: string;
+  nodeType: NodeTypeBadgeType;
+};
+
+export function NodeTypeBadge({
+  className,
+  label,
+  nodeType,
+  ...props
+}: NodeTypeBadgeProps) {
+  return (
+    <Badge
+      className={cn(getNodeTypeBadgeClasses(nodeType), className)}
+      {...props}
+    >
+      {label ?? humanizeNodeType(nodeType)}
+    </Badge>
+  );
+}
diff --git a/packages/ui/src/page-shell.tsx b/packages/ui/src/page-shell.tsx
new file mode 100644
index 0000000..c0106bd
--- /dev/null
+++ b/packages/ui/src/page-shell.tsx
@@ -0,0 +1,18 @@
+import type { HTMLAttributes } from "react";
+
+import { cn } from "./utils";
+
+export function PageShell({
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn(
+        "mx-auto flex w-full max-w-6xl flex-col gap-[var(--gg-space-8)] px-[var(--gg-space-6)] py-[var(--gg-space-6)] sm:px-[var(--gg-space-8)] lg:px-[var(--gg-space-10)] lg:py-[var(--gg-space-10)]",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
diff --git a/packages/ui/src/section-header.tsx b/packages/ui/src/section-header.tsx
new file mode 100644
index 0000000..f11cab6
--- /dev/null
+++ b/packages/ui/src/section-header.tsx
@@ -0,0 +1,52 @@
+import type { HTMLAttributes, ReactNode } from "react";
+
+import { cn } from "./utils";
+
+type SectionHeaderProps = Omit<HTMLAttributes<HTMLDivElement>, "title"> & {
+  eyebrow?: ReactNode;
+  title: ReactNode;
+  description?: ReactNode;
+  trailing?: ReactNode;
+};
+
+export function SectionHeader({
+  className,
+  description,
+  eyebrow,
+  title,
+  trailing,
+  ...props
+}: SectionHeaderProps) {
+  return (
+    <div
+      className={cn(
+        "flex flex-col gap-[var(--gg-space-3)] sm:flex-row sm:items-end sm:justify-between",
+        className,
+      )}
+      {...props}
+    >
+      <div className="space-y-[var(--gg-space-2)]">
+        {eyebrow ? (
+          <p className="text-[length:var(--gg-font-size-xs)] font-semibold uppercase tracking-[var(--gg-font-letter-spacing-eyebrow)] text-[var(--gg-color-semantic-text-secondary)]">
+            {eyebrow}
+          </p>
+        ) : null}
+        <div className="space-y-[var(--gg-space-1)]">
+          <h2 className="font-[family-name:var(--gg-font-family-display)] text-[length:var(--gg-font-size-3xl)] font-semibold tracking-[var(--gg-font-letter-spacing-tight)] text-[var(--gg-color-ink)] sm:text-[length:var(--gg-font-size-4xl)]">
+            {title}
+          </h2>
+          {description ? (
+            <p className="max-w-3xl text-[length:var(--gg-font-size-sm)] leading-[var(--gg-font-line-height-body)] text-[var(--gg-color-semantic-text-secondary)]">
+              {description}
+            </p>
+          ) : null}
+        </div>
+      </div>
+      {trailing ? (
+        <div className="text-[length:var(--gg-font-size-sm)] text-[var(--gg-color-semantic-text-secondary)]">
+          {trailing}
+        </div>
+      ) : null}
+    </div>
+  );
+}
diff --git a/packages/ui/src/site-header.tsx b/packages/ui/src/site-header.tsx
new file mode 100644
index 0000000..dfbabd4
--- /dev/null
+++ b/packages/ui/src/site-header.tsx
@@ -0,0 +1,37 @@
+import type { HTMLAttributes, ReactNode } from "react";
+
+import { cn } from "./utils";
+
+type SiteHeaderProps = HTMLAttributes<HTMLElement> & {
+  brand: ReactNode;
+  navigation?: ReactNode;
+  utility?: ReactNode;
+};
+
+export function SiteHeader({
+  brand,
+  navigation,
+  utility,
+  className,
+  ...props
+}: SiteHeaderProps) {
+  return (
+    <header
+      className={cn(
+        "sticky top-0 z-20 border-b border-[var(--gg-color-border)] bg-[color:rgba(246,241,230,0.95)] backdrop-blur-sm",
+        className,
+      )}
+      {...props}
+    >
+      <div className="mx-auto flex w-full max-w-6xl flex-col gap-[var(--gg-space-4)] px-[var(--gg-space-6)] py-[var(--gg-space-4)] sm:px-[var(--gg-space-8)] lg:flex-row lg:items-center lg:justify-between lg:px-[var(--gg-space-10)]">
+        <div className="min-w-0">{brand}</div>
+        {navigation ? (
+          <nav className="flex flex-wrap items-center gap-[var(--gg-space-4)] text-[length:var(--gg-font-size-sm)] font-medium text-[var(--gg-color-semantic-text-secondary)]">
+            {navigation}
+          </nav>
+        ) : null}
+        {utility ? <div className="flex items-center gap-[var(--gg-space-3)]">{utility}</div> : null}
+      </div>
+    </header>
+  );
+}
diff --git a/packages/ui/src/skeleton.tsx b/packages/ui/src/skeleton.tsx
new file mode 100644
index 0000000..96e8b54
--- /dev/null
+++ b/packages/ui/src/skeleton.tsx
@@ -0,0 +1,31 @@
+import type { HTMLAttributes } from "react";
+
+import { cn } from "./utils";
+
+type SkeletonProps = HTMLAttributes<HTMLDivElement> & {
+  shape?: "line" | "card" | "pill";
+};
+
+const shapeClasses = {
+  line: "h-4 rounded-[var(--gg-radius-full)]",
+  card: "h-32 rounded-[var(--gg-radius-lg)]",
+  pill: "h-9 rounded-[var(--gg-radius-full)]",
+} as const;
+
+export function Skeleton({
+  className,
+  shape = "line",
+  ...props
+}: SkeletonProps) {
+  return (
+    <div
+      className={cn(
+        "relative overflow-hidden bg-[var(--gg-color-wash)]",
+        "after:absolute after:inset-0 after:animate-[gg-shimmer_1.6s_ease-in-out_infinite] after:bg-[linear-gradient(90deg,transparent,rgba(255,255,255,0.55),transparent)]",
+        shapeClasses[shape],
+        className,
+      )}
+      {...props}
+    />
+  );
+}
diff --git a/packages/ui/src/source-card.tsx b/packages/ui/src/source-card.tsx
new file mode 100644
index 0000000..e0de226
--- /dev/null
+++ b/packages/ui/src/source-card.tsx
@@ -0,0 +1,44 @@
+import type { HTMLAttributes, ReactNode } from "react";
+
+import { Card } from "./card";
+import { cn } from "./utils";
+
+type SourceCardProps = Omit<HTMLAttributes<HTMLDivElement>, "title"> & {
+  badges?: ReactNode;
+  description?: ReactNode;
+  metadata?: ReactNode;
+  action?: ReactNode;
+  title: ReactNode;
+};
+
+export function SourceCard({
+  action,
+  badges,
+  className,
+  description,
+  metadata,
+  title,
+  ...props
+}: SourceCardProps) {
+  return (
+    <Card className={cn("p-[var(--gg-space-5)]", className)} {...props}>
+      {badges ? <div className="flex flex-wrap gap-[var(--gg-space-3)]">{badges}</div> : null}
+      <div className="mt-[var(--gg-space-4)] space-y-[var(--gg-space-2)]">
+        <div className="font-[family-name:var(--gg-font-family-display)] text-[length:var(--gg-font-size-xl)] font-semibold tracking-[var(--gg-font-letter-spacing-tight)] text-[var(--gg-color-ink)]">
+          {title}
+        </div>
+        {description ? (
+          <div className="text-[length:var(--gg-font-size-sm)] leading-[var(--gg-font-line-height-body)] text-[var(--gg-color-semantic-text-secondary)]">
+            {description}
+          </div>
+        ) : null}
+        {metadata ? (
+          <div className="text-[length:var(--gg-font-size-xs)] font-semibold uppercase tracking-[var(--gg-font-letter-spacing-caps)] text-[var(--gg-color-semantic-text-secondary)]">
+            {metadata}
+          </div>
+        ) : null}
+      </div>
+      {action ? <div className="mt-[var(--gg-space-4)]">{action}</div> : null}
+    </Card>
+  );
+}
diff --git a/packages/ui/src/stat-card.tsx b/packages/ui/src/stat-card.tsx
new file mode 100644
index 0000000..cea5ff9
--- /dev/null
+++ b/packages/ui/src/stat-card.tsx
@@ -0,0 +1,32 @@
+import type { HTMLAttributes, ReactNode } from "react";
+
+import { Card } from "./card";
+import { cn } from "./utils";
+
+type StatCardProps = HTMLAttributes<HTMLDivElement> & {
+  label: ReactNode;
+  value: ReactNode;
+  description: ReactNode;
+};
+
+export function StatCard({
+  className,
+  description,
+  label,
+  value,
+  ...props
+}: StatCardProps) {
+  return (
+    <Card className={cn("p-[var(--gg-space-5)]", className)} {...props}>
+      <p className="text-[length:var(--gg-font-size-xs)] font-semibold uppercase tracking-[var(--gg-font-letter-spacing-caps)] text-[var(--gg-color-semantic-text-secondary)]">
+        {label}
+      </p>
+      <p className="mt-[var(--gg-space-4)] font-[family-name:var(--gg-font-family-display)] text-[length:var(--gg-font-size-4xl)] font-semibold tracking-[var(--gg-font-letter-spacing-tight)] text-[var(--gg-color-ink)]">
+        {value}
+      </p>
+      <p className="mt-[var(--gg-space-2)] text-[length:var(--gg-font-size-sm)] leading-[var(--gg-font-line-height-body)] text-[var(--gg-color-semantic-text-secondary)]">
+        {description}
+      </p>
+    </Card>
+  );
+}
diff --git a/packages/ui/src/textarea.tsx b/packages/ui/src/textarea.tsx
new file mode 100644
index 0000000..d36656b
--- /dev/null
+++ b/packages/ui/src/textarea.tsx
@@ -0,0 +1,18 @@
+import type { TextareaHTMLAttributes } from "react";
+
+import { cn } from "./utils";
+
+export function Textarea({
+  className,
+  ...props
+}: TextareaHTMLAttributes<HTMLTextAreaElement>) {
+  return (
+    <textarea
+      className={cn(
+        "min-h-32 w-full rounded-[var(--gg-radius-md)] border border-[var(--gg-color-border)] bg-[var(--gg-color-semantic-surface-strong)] px-[var(--gg-space-5)] py-[var(--gg-space-4)] text-[length:var(--gg-font-size-base)] text-[var(--gg-color-ink)] shadow-[var(--gg-shadow-sm)] outline-none transition-[color,background-color,border-color,box-shadow] duration-[var(--gg-animation-duration-normal)] ease-[var(--gg-animation-easing-standard)] placeholder:text-[var(--gg-color-muted)] focus:border-[var(--gg-color-deep)] focus:ring-2 focus:ring-[var(--gg-color-semantic-focus-ring)]",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
diff --git a/packages/ui/src/timeline-entry.tsx b/packages/ui/src/timeline-entry.tsx
new file mode 100644
index 0000000..b5c9a7a
--- /dev/null
+++ b/packages/ui/src/timeline-entry.tsx
@@ -0,0 +1,45 @@
+import type { HTMLAttributes, ReactNode } from "react";
+
+import { Card } from "./card";
+import { cn } from "./utils";
+
+type TimelineEntryProps = Omit<HTMLAttributes<HTMLDivElement>, "title"> & {
+  date: ReactNode;
+  description?: ReactNode;
+  detail?: ReactNode;
+  title: ReactNode;
+};
+
+export function TimelineEntry({
+  className,
+  date,
+  description,
+  detail,
+  title,
+  ...props
+}: TimelineEntryProps) {
+  return (
+    <Card className={cn("relative overflow-hidden p-[var(--gg-space-5)]", className)} {...props}>
+      <div className="absolute left-[var(--gg-space-5)] top-[var(--gg-space-5)] h-[calc(100%-var(--gg-space-10))] w-px bg-[var(--gg-color-border)]" />
+      <div className="relative pl-[var(--gg-space-6)]">
+        <div className="absolute left-0 top-[0.35rem] h-3 w-3 rounded-[var(--gg-radius-full)] border border-[var(--gg-color-accent)] bg-[var(--gg-color-paper)]" />
+        <p className="text-[length:var(--gg-font-size-xs)] font-semibold uppercase tracking-[var(--gg-font-letter-spacing-caps)] text-[var(--gg-color-semantic-text-secondary)]">
+          {date}
+        </p>
+        <h3 className="mt-[var(--gg-space-2)] font-[family-name:var(--gg-font-family-display)] text-[length:var(--gg-font-size-xl)] font-semibold tracking-[var(--gg-font-letter-spacing-tight)] text-[var(--gg-color-ink)]">
+          {title}
+        </h3>
+        {description ? (
+          <p className="mt-[var(--gg-space-2)] text-[length:var(--gg-font-size-sm)] leading-[var(--gg-font-line-height-body)] text-[var(--gg-color-semantic-text-secondary)]">
+            {description}
+          </p>
+        ) : null}
+        {detail ? (
+          <div className="mt-[var(--gg-space-3)] text-[length:var(--gg-font-size-xs)] font-semibold uppercase tracking-[var(--gg-font-letter-spacing-caps)] text-[var(--gg-color-semantic-text-secondary)]">
+            {detail}
+          </div>
+        ) : null}
+      </div>
+    </Card>
+  );
+}
diff --git a/packages/ui/src/tokens/animation.ts b/packages/ui/src/tokens/animation.ts
new file mode 100644
index 0000000..27640e4
--- /dev/null
+++ b/packages/ui/src/tokens/animation.ts
@@ -0,0 +1,10 @@
+export const animation = {
+  duration: {
+    fast: "100ms",
+    normal: "160ms",
+    slow: "300ms",
+  },
+  easing: {
+    standard: "ease",
+  },
+} as const;
diff --git a/packages/ui/src/tokens/colors.ts b/packages/ui/src/tokens/colors.ts
new file mode 100644
index 0000000..b5c024a
--- /dev/null
+++ b/packages/ui/src/tokens/colors.ts
@@ -0,0 +1,97 @@
+export const colors = {
+  paper: "#f6f1e6",
+  "paper-strong": "#fffaf1",
+  ink: "#0e2c24",
+  deep: "#163e35",
+  accent: "#b94a37",
+  border: "rgba(14, 44, 36, 0.14)",
+  "border-strong": "rgba(14, 44, 36, 0.24)",
+  muted: "#5a675f",
+  wash: "#edf1eb",
+  "wash-strong": "#dfe8dc",
+  white: "#ffffff",
+  semantic: {
+    surface: "rgba(255, 250, 241, 0.88)",
+    "surface-strong": "rgba(255, 255, 255, 0.94)",
+    "surface-muted": "rgba(237, 241, 235, 0.82)",
+    "text-primary": "var(--gg-color-ink)",
+    "text-secondary": "var(--gg-color-muted)",
+    "text-link": "var(--gg-color-deep)",
+    "focus-ring": "rgba(14, 44, 36, 0.16)",
+    danger: "#9f3f32",
+    success: "#2f6b57",
+    warning: "#8a6821",
+  },
+  node: {
+    person: {
+      bg: "#e7f0ec",
+      border: "#bfd2ca",
+      text: "#28483d",
+    },
+    ministry: {
+      bg: "#f1ece2",
+      border: "#d9cdb9",
+      text: "#4b3d22",
+    },
+    portfolio: {
+      bg: "#f4e4dd",
+      border: "#debaa9",
+      text: "#6f3b2f",
+    },
+    department: {
+      bg: "#e6edee",
+      border: "#bbcdd0",
+      text: "#26494f",
+    },
+    administrative_office: {
+      bg: "#ece8f1",
+      border: "#c9bfd7",
+      text: "#493764",
+    },
+    public_entity: {
+      bg: "#edf0e4",
+      border: "#c9d3b2",
+      text: "#4e5d2d",
+    },
+    program_output: {
+      bg: "#f6e8d8",
+      border: "#e2c59d",
+      text: "#7b5523",
+    },
+    capital_project: {
+      bg: "#f3e2d6",
+      border: "#dfbba4",
+      text: "#744630",
+    },
+    performance_measure: {
+      bg: "#e2eeeb",
+      border: "#b4d0c6",
+      text: "#2d5d52",
+    },
+    budget_document: {
+      bg: "#f2ead5",
+      border: "#dbcaa0",
+      text: "#6c5523",
+    },
+    source_document: {
+      bg: "#ebe8e2",
+      border: "#ccc4b7",
+      text: "#52473a",
+    },
+    organisation_group: {
+      bg: "#ede4df",
+      border: "#cfbeb2",
+      text: "#5c4438",
+    },
+  },
+} as const;
+
+export const legacyGovGraphAliases = {
+  paper: "var(--gg-color-paper)",
+  ink: "var(--gg-color-ink)",
+  deep: "var(--gg-color-deep)",
+  accent: "var(--gg-color-accent)",
+  border: "var(--gg-color-border)",
+  muted: "var(--gg-color-muted)",
+  wash: "var(--gg-color-wash)",
+} as const;
diff --git a/packages/ui/src/tokens/generate-css.ts b/packages/ui/src/tokens/generate-css.ts
new file mode 100644
index 0000000..0bc786c
--- /dev/null
+++ b/packages/ui/src/tokens/generate-css.ts
@@ -0,0 +1,49 @@
+type TokenValue = string | TokenTree;
+
+export type TokenTree = {
+  readonly [key: string]: TokenValue;
+};
+
+function isTokenTree(value: TokenValue): value is TokenTree {
+  return typeof value !== "string";
+}
+
+function toKebabCase(value: string): string {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/_/g, "-")
+    .toLowerCase();
+}
+
+function flattenTokenTree(
+  tree: TokenTree,
+  prefix: readonly string[],
+): string[] {
+  const declarations: string[] = [];
+
+  for (const [key, value] of Object.entries(tree)) {
+    const path = [...prefix, toKebabCase(key)];
+
+    if (isTokenTree(value)) {
+      declarations.push(...flattenTokenTree(value, path));
+      continue;
+    }
+
+    declarations.push(`  --${path.join("-")}: ${value};`);
+  }
+
+  return declarations;
+}
+
+export function generateCssCustomProperties(
+  tree: TokenTree,
+  options: {
+    prefix: string;
+    selector?: string;
+  },
+): string {
+  const selector = options.selector ?? ":root";
+  const declarations = flattenTokenTree(tree, [options.prefix]);
+
+  return `${selector} {\n${declarations.join("\n")}\n}`;
+}
diff --git a/packages/ui/src/tokens/generated.css b/packages/ui/src/tokens/generated.css
new file mode 100644
index 0000000..f0588d8
--- /dev/null
+++ b/packages/ui/src/tokens/generated.css
@@ -0,0 +1,143 @@
+/* This file is generated from packages/ui/src/tokens. */
+
+:root {
+  --gg-color-paper: #f6f1e6;
+  --gg-color-paper-strong: #fffaf1;
+  --gg-color-ink: #0e2c24;
+  --gg-color-deep: #163e35;
+  --gg-color-accent: #b94a37;
+  --gg-color-border: rgba(14, 44, 36, 0.14);
+  --gg-color-border-strong: rgba(14, 44, 36, 0.24);
+  --gg-color-muted: #5a675f;
+  --gg-color-wash: #edf1eb;
+  --gg-color-wash-strong: #dfe8dc;
+  --gg-color-white: #ffffff;
+  --gg-color-semantic-surface: rgba(255, 250, 241, 0.88);
+  --gg-color-semantic-surface-strong: rgba(255, 255, 255, 0.94);
+  --gg-color-semantic-surface-muted: rgba(237, 241, 235, 0.82);
+  --gg-color-semantic-text-primary: var(--gg-color-ink);
+  --gg-color-semantic-text-secondary: var(--gg-color-muted);
+  --gg-color-semantic-text-link: var(--gg-color-deep);
+  --gg-color-semantic-focus-ring: rgba(14, 44, 36, 0.16);
+  --gg-color-semantic-danger: #9f3f32;
+  --gg-color-semantic-success: #2f6b57;
+  --gg-color-semantic-warning: #8a6821;
+  --gg-color-node-person-bg: #e7f0ec;
+  --gg-color-node-person-border: #bfd2ca;
+  --gg-color-node-person-text: #28483d;
+  --gg-color-node-ministry-bg: #f1ece2;
+  --gg-color-node-ministry-border: #d9cdb9;
+  --gg-color-node-ministry-text: #4b3d22;
+  --gg-color-node-portfolio-bg: #f4e4dd;
+  --gg-color-node-portfolio-border: #debaa9;
+  --gg-color-node-portfolio-text: #6f3b2f;
+  --gg-color-node-department-bg: #e6edee;
+  --gg-color-node-department-border: #bbcdd0;
+  --gg-color-node-department-text: #26494f;
+  --gg-color-node-administrative-office-bg: #ece8f1;
+  --gg-color-node-administrative-office-border: #c9bfd7;
+  --gg-color-node-administrative-office-text: #493764;
+  --gg-color-node-public-entity-bg: #edf0e4;
+  --gg-color-node-public-entity-border: #c9d3b2;
+  --gg-color-node-public-entity-text: #4e5d2d;
+  --gg-color-node-program-output-bg: #f6e8d8;
+  --gg-color-node-program-output-border: #e2c59d;
+  --gg-color-node-program-output-text: #7b5523;
+  --gg-color-node-capital-project-bg: #f3e2d6;
+  --gg-color-node-capital-project-border: #dfbba4;
+  --gg-color-node-capital-project-text: #744630;
+  --gg-color-node-performance-measure-bg: #e2eeeb;
+  --gg-color-node-performance-measure-border: #b4d0c6;
+  --gg-color-node-performance-measure-text: #2d5d52;
+  --gg-color-node-budget-document-bg: #f2ead5;
+  --gg-color-node-budget-document-border: #dbcaa0;
+  --gg-color-node-budget-document-text: #6c5523;
+  --gg-color-node-source-document-bg: #ebe8e2;
+  --gg-color-node-source-document-border: #ccc4b7;
+  --gg-color-node-source-document-text: #52473a;
+  --gg-color-node-organisation-group-bg: #ede4df;
+  --gg-color-node-organisation-group-border: #cfbeb2;
+  --gg-color-node-organisation-group-text: #5c4438;
+  --gg-font-family-display: var(--font-display), "Iowan Old Style", Georgia, serif;
+  --gg-font-family-body: var(--font-body), "Helvetica Neue", Arial, sans-serif;
+  --gg-font-family-mono: var(--font-mono), "SFMono-Regular", monospace;
+  --gg-font-size-xs: 0.75rem;
+  --gg-font-size-sm: 0.875rem;
+  --gg-font-size-base: 1rem;
+  --gg-font-size-lg: 1.125rem;
+  --gg-font-size-xl: 1.25rem;
+  --gg-font-size-2xl: 1.5rem;
+  --gg-font-size-3xl: 1.875rem;
+  --gg-font-size-4xl: 2.25rem;
+  --gg-font-size-5xl: 3rem;
+  --gg-font-size-6xl: 3.75rem;
+  --gg-font-weight-regular: 400;
+  --gg-font-weight-medium: 500;
+  --gg-font-weight-semibold: 600;
+  --gg-font-weight-bold: 700;
+  --gg-font-line-height-tight: 1.1;
+  --gg-font-line-height-snug: 1.25;
+  --gg-font-line-height-body: 1.6;
+  --gg-font-line-height-relaxed: 1.8;
+  --gg-font-letter-spacing-tight: -0.03em;
+  --gg-font-letter-spacing-normal: 0em;
+  --gg-font-letter-spacing-caps: 0.18em;
+  --gg-font-letter-spacing-eyebrow: 0.24em;
+  --gg-font-heading-eyebrow-size: var(--gg-font-size-xs);
+  --gg-font-heading-eyebrow-weight: var(--gg-font-weight-semibold);
+  --gg-font-heading-eyebrow-line-height: var(--gg-font-line-height-snug);
+  --gg-font-heading-eyebrow-letter-spacing: var(--gg-font-letter-spacing-eyebrow);
+  --gg-font-heading-section-size: var(--gg-font-size-3xl);
+  --gg-font-heading-section-weight: var(--gg-font-weight-semibold);
+  --gg-font-heading-section-line-height: var(--gg-font-line-height-tight);
+  --gg-font-heading-section-letter-spacing: var(--gg-font-letter-spacing-tight);
+  --gg-font-heading-display-size: var(--gg-font-size-6xl);
+  --gg-font-heading-display-weight: var(--gg-font-weight-semibold);
+  --gg-font-heading-display-line-height: var(--gg-font-line-height-tight);
+  --gg-font-heading-display-letter-spacing: var(--gg-font-letter-spacing-tight);
+  --gg-space-0: 0rem;
+  --gg-space-1: 0.25rem;
+  --gg-space-2: 0.5rem;
+  --gg-space-3: 0.75rem;
+  --gg-space-4: 1rem;
+  --gg-space-5: 1.25rem;
+  --gg-space-6: 1.5rem;
+  --gg-space-8: 2rem;
+  --gg-space-10: 2.5rem;
+  --gg-space-12: 3rem;
+  --gg-space-16: 4rem;
+  --gg-space-20: 5rem;
+  --gg-space-24: 6rem;
+  --gg-radius-sm: 0.75rem;
+  --gg-radius-md: 1rem;
+  --gg-radius-lg: 1.75rem;
+  --gg-radius-xl: 2rem;
+  --gg-radius-2xl: 2.5rem;
+  --gg-radius-full: 9999px;
+  --gg-shadow-sm: 0 10px 30px rgba(14, 44, 36, 0.06);
+  --gg-shadow-md: 0 18px 48px rgba(14, 44, 36, 0.08);
+  --gg-shadow-lg: 0 30px 90px rgba(14, 44, 36, 0.09);
+  --gg-animation-duration-fast: 100ms;
+  --gg-animation-duration-normal: 160ms;
+  --gg-animation-duration-slow: 300ms;
+  --gg-animation-easing-standard: ease;
+}
+
+:root {
+  --govgraph-paper: var(--gg-color-paper);
+  --govgraph-ink: var(--gg-color-ink);
+  --govgraph-deep: var(--gg-color-deep);
+  --govgraph-accent: var(--gg-color-accent);
+  --govgraph-border: var(--gg-color-border);
+  --govgraph-muted: var(--gg-color-muted);
+  --govgraph-wash: var(--gg-color-wash);
+}
+
+@keyframes gg-shimmer {
+  0% {
+    transform: translateX(-100%);
+  }
+  100% {
+    transform: translateX(100%);
+  }
+}
diff --git a/packages/ui/src/tokens/index.test.ts b/packages/ui/src/tokens/index.test.ts
new file mode 100644
index 0000000..9827b63
--- /dev/null
+++ b/packages/ui/src/tokens/index.test.ts
@@ -0,0 +1,26 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { buildGovGraphTokenCss } from "./index";
+
+const currentDirectory = dirname(fileURLToPath(import.meta.url));
+const generatedCssPath = resolve(currentDirectory, "generated.css");
+
+describe("buildGovGraphTokenCss", () => {
+  it("includes core token variables and legacy aliases", () => {
+    const css = buildGovGraphTokenCss();
+
+    expect(css).toContain("--gg-color-paper: #f6f1e6;");
+    expect(css).toContain("--gg-font-size-3xl: 1.875rem;");
+    expect(css).toContain("--gg-radius-lg: 1.75rem;");
+    expect(css).toContain("--govgraph-paper: var(--gg-color-paper);");
+    expect(css).toContain("@keyframes gg-shimmer");
+  });
+
+  it("matches the committed generated stylesheet", () => {
+    const committedCss = readFileSync(generatedCssPath, "utf8");
+
+    expect(committedCss).toBe(`${buildGovGraphTokenCss()}\n`);
+  });
+});
diff --git a/packages/ui/src/tokens/index.ts b/packages/ui/src/tokens/index.ts
new file mode 100644
index 0000000..d76d67a
--- /dev/null
+++ b/packages/ui/src/tokens/index.ts
@@ -0,0 +1,46 @@
+import { animation } from "./animation";
+import { colors, legacyGovGraphAliases } from "./colors";
+import { generateCssCustomProperties } from "./generate-css";
+import { radii } from "./radii";
+import { shadows } from "./shadows";
+import { spacing } from "./spacing";
+import { typography } from "./typography";
+
+export { animation } from "./animation";
+export { colors, legacyGovGraphAliases } from "./colors";
+export { generateCssCustomProperties } from "./generate-css";
+export { radii } from "./radii";
+export { shadows } from "./shadows";
+export { spacing } from "./spacing";
+export { typography } from "./typography";
+
+export const govGraphTokens = {
+  color: colors,
+  font: typography,
+  space: spacing,
+  radius: radii,
+  shadow: shadows,
+  animation,
+} as const;
+
+export function buildGovGraphTokenCss(): string {
+  return [
+    "/* This file is generated from packages/ui/src/tokens. */",
+    generateCssCustomProperties(govGraphTokens, { prefix: "gg" }),
+    generateCssCustomProperties(legacyGovGraphAliases, {
+      prefix: "govgraph",
+    }),
+    [
+      "@keyframes gg-shimmer {",
+      "  0% {",
+      "    transform: translateX(-100%);",
+      "  }",
+      "  100% {",
+      "    transform: translateX(100%);",
+      "  }",
+      "}",
+    ].join("\n"),
+  ].join("\n\n");
+}
+
+export const govGraphTokenCss = buildGovGraphTokenCss();
diff --git a/packages/ui/src/tokens/radii.ts b/packages/ui/src/tokens/radii.ts
new file mode 100644
index 0000000..0b075ea
--- /dev/null
+++ b/packages/ui/src/tokens/radii.ts
@@ -0,0 +1,8 @@
+export const radii = {
+  sm: "0.75rem",
+  md: "1rem",
+  lg: "1.75rem",
+  xl: "2rem",
+  "2xl": "2.5rem",
+  full: "9999px",
+} as const;
diff --git a/packages/ui/src/tokens/shadows.ts b/packages/ui/src/tokens/shadows.ts
new file mode 100644
index 0000000..22510b8
--- /dev/null
+++ b/packages/ui/src/tokens/shadows.ts
@@ -0,0 +1,5 @@
+export const shadows = {
+  sm: "0 10px 30px rgba(14, 44, 36, 0.06)",
+  md: "0 18px 48px rgba(14, 44, 36, 0.08)",
+  lg: "0 30px 90px rgba(14, 44, 36, 0.09)",
+} as const;
diff --git a/packages/ui/src/tokens/spacing.ts b/packages/ui/src/tokens/spacing.ts
new file mode 100644
index 0000000..258ecd9
--- /dev/null
+++ b/packages/ui/src/tokens/spacing.ts
@@ -0,0 +1,15 @@
+export const spacing = {
+  "0": "0rem",
+  "1": "0.25rem",
+  "2": "0.5rem",
+  "3": "0.75rem",
+  "4": "1rem",
+  "5": "1.25rem",
+  "6": "1.5rem",
+  "8": "2rem",
+  "10": "2.5rem",
+  "12": "3rem",
+  "16": "4rem",
+  "20": "5rem",
+  "24": "6rem",
+} as const;
diff --git a/packages/ui/src/tokens/typography.ts b/packages/ui/src/tokens/typography.ts
new file mode 100644
index 0000000..c08f6a8
--- /dev/null
+++ b/packages/ui/src/tokens/typography.ts
@@ -0,0 +1,57 @@
+export const typography = {
+  family: {
+    display: 'var(--font-display), "Iowan Old Style", Georgia, serif',
+    body: 'var(--font-body), "Helvetica Neue", Arial, sans-serif',
+    mono: 'var(--font-mono), "SFMono-Regular", monospace',
+  },
+  size: {
+    xs: "0.75rem",
+    sm: "0.875rem",
+    base: "1rem",
+    lg: "1.125rem",
+    xl: "1.25rem",
+    "2xl": "1.5rem",
+    "3xl": "1.875rem",
+    "4xl": "2.25rem",
+    "5xl": "3rem",
+    "6xl": "3.75rem",
+  },
+  weight: {
+    regular: "400",
+    medium: "500",
+    semibold: "600",
+    bold: "700",
+  },
+  "line-height": {
+    tight: "1.1",
+    snug: "1.25",
+    body: "1.6",
+    relaxed: "1.8",
+  },
+  "letter-spacing": {
+    tight: "-0.03em",
+    normal: "0em",
+    caps: "0.18em",
+    eyebrow: "0.24em",
+  },
+  heading: {
+    eyebrow: {
+      size: "var(--gg-font-size-xs)",
+      weight: "var(--gg-font-weight-semibold)",
+      "line-height": "var(--gg-font-line-height-snug)",
+      "letter-spacing": "var(--gg-font-letter-spacing-eyebrow)",
+    },
+    section: {
+      size: "var(--gg-font-size-3xl)",
+      weight: "var(--gg-font-weight-semibold)",
+      "line-height": "var(--gg-font-line-height-tight)",
+      "letter-spacing": "var(--gg-font-letter-spacing-tight)",
+    },
+    display: {
+      size: "var(--gg-font-size-6xl)",
+      weight: "var(--gg-font-weight-semibold)",
+      "line-height": "var(--gg-font-line-height-tight)",
+      "letter-spacing": "var(--gg-font-letter-spacing-tight)",
+    },
+  },
+} as const;
diff --git a/packages/ui/src/tooltip.tsx b/packages/ui/src/tooltip.tsx
new file mode 100644
index 0000000..8ac3cd7
--- /dev/null
+++ b/packages/ui/src/tooltip.tsx
@@ -0,0 +1,27 @@
+import type { HTMLAttributes, ReactNode } from "react";
+
+import { cn } from "./utils";
+
+type TooltipProps = HTMLAttributes<HTMLSpanElement> & {
+  content: ReactNode;
+  children: ReactNode;
+};
+
+export function Tooltip({
+  children,
+  className,
+  content,
+  ...props
+}: TooltipProps) {
+  return (
+    <span className={cn("group relative inline-flex", className)} {...props}>
+      {children}
+      <span
+        role="tooltip"
+        className="pointer-events-none absolute bottom-[calc(100%+var(--gg-space-2))] left-1/2 z-10 w-max max-w-64 -translate-x-1/2 rounded-[var(--gg-radius-md)] border border-[var(--gg-color-border)] bg-[var(--gg-color-paper-strong)] px-[var(--gg-space-3)] py-[var(--gg-space-2)] text-[length:var(--gg-font-size-xs)] leading-[var(--gg-font-line-height-body)] text-[var(--gg-color-ink)] opacity-0 shadow-[var(--gg-shadow-sm)] transition-[opacity,transform] duration-[var(--gg-animation-duration-normal)] ease-[var(--gg-animation-easing-standard)] group-hover:-translate-y-1 group-hover:opacity-100 group-focus-within:-translate-y-1 group-focus-within:opacity-100"
+      >
+        {content}
+      </span>
+    </span>
+  );
+}
diff --git a/packages/ui/tsconfig.json b/packages/ui/tsconfig.json
index e86e4e0..d0d92a9 100644
--- a/packages/ui/tsconfig.json
+++ b/packages/ui/tsconfig.json
@@ -1,4 +1,7 @@
 {
   "extends": "../config/ts/react-library.json",
+  "compilerOptions": {
+    "types": ["node", "vitest/globals"]
+  },
   "include": ["src/**/*.ts", "src/**/*.tsx"]
 }

From c9788918b3101bd9f19484b233a4cc2708f6f829 Mon Sep 17 00:00:00 2001
From: David Diviny <david.diviny@gmail.com>
Date: Wed, 8 Apr 2026 06:17:27 +1000
Subject: [PATCH 2/3] Sync lockfile for design system tooling

---
 pnpm-lock.yaml | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f8d4beb..7f7dc06 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -147,6 +147,9 @@ importers:
         specifier: ^3.3.1
         version: 3.5.0
     devDependencies:
+      '@types/node':
+        specifier: ^24.12.2
+        version: 24.12.2
       '@types/react':
         specifier: ^19.2.2
         version: 19.2.14
@@ -159,6 +162,9 @@ importers:
       react-dom:
         specifier: ^19.2.0
         version: 19.2.4(react@19.2.4)
+      vitest:
+        specifier: ^3.2.4
+        version: 3.2.4(@types/node@24.12.2)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)
 
 packages:
 
@@ -5412,7 +5418,7 @@ snapshots:
       eslint: 9.39.4(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.10
       eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.58.0(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.4(jiti@2.6.1)))(eslint@9.39.4(jiti@2.6.1))
-      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.58.0(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.4(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.58.0(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.58.0(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.4(jiti@2.6.1)))(eslint@9.39.4(jiti@2.6.1)))(eslint@9.39.4(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.4(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.4(jiti@2.6.1))
       eslint-plugin-react-hooks: 7.0.1(eslint@9.39.4(jiti@2.6.1))
@@ -5445,7 +5451,7 @@ snapshots:
       tinyglobby: 0.2.15
       unrs-resolver: 1.11.1
     optionalDependencies:
-      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.58.0(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.4(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.58.0(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.58.0(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.4(jiti@2.6.1)))(eslint@9.39.4(jiti@2.6.1)))(eslint@9.39.4(jiti@2.6.1))
     transitivePeerDependencies:
       - supports-color
 
@@ -5460,7 +5466,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.58.0(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.4(jiti@2.6.1)):
+  eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.58.0(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.58.0(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.4(jiti@2.6.1)))(eslint@9.39.4(jiti@2.6.1)))(eslint@9.39.4(jiti@2.6.1)):
     dependencies:
       '@rtsao/scc': 1.1.0
       array-includes: 3.1.9

From 6e5e736a3c6438ef8b053169beeba24bc4a5c6e9 Mon Sep 17 00:00:00 2001
From: David Diviny <david.diviny@gmail.com>
Date: Wed, 8 Apr 2026 06:31:51 +1000
Subject: [PATCH 3/3] Address PR review feedback

---
 .../web/app/_components/relationship-list.tsx |  2 +-
 apps/web/app/nodes/[slug]/page.tsx            |  6 +-
 apps/web/app/not-found.tsx                    |  5 +-
 packages/ui/src/data-table-row-key.test.ts    | 67 +++++++++++++++++++
 packages/ui/src/data-table-row-key.ts         | 26 +++++++
 packages/ui/src/data-table.tsx                | 11 ++-
 6 files changed, 109 insertions(+), 8 deletions(-)
 create mode 100644 packages/ui/src/data-table-row-key.test.ts
 create mode 100644 packages/ui/src/data-table-row-key.ts

diff --git a/apps/web/app/_components/relationship-list.tsx b/apps/web/app/_components/relationship-list.tsx
index 9692ef4..0246cdd 100644
--- a/apps/web/app/_components/relationship-list.tsx
+++ b/apps/web/app/_components/relationship-list.tsx
@@ -20,7 +20,7 @@ export function RelationshipList({ relatedNodes }: RelationshipListProps) {
   }
 
   return (
-    <div className="grid gap-4">
+    <div className="grid gap-[var(--gg-space-4)]">
       {relatedNodes.map((entry) => (
         <NodeCard
           key={`${entry.edgeType}-${entry.direction}-${entry.node.id}`}
diff --git a/apps/web/app/nodes/[slug]/page.tsx b/apps/web/app/nodes/[slug]/page.tsx
index d0dff3a..aa25ffe 100644
--- a/apps/web/app/nodes/[slug]/page.tsx
+++ b/apps/web/app/nodes/[slug]/page.tsx
@@ -17,7 +17,7 @@ import {
 
 import { RelationshipList } from "../../_components/relationship-list";
 import { SearchForm } from "../../_components/search-form";
-import { humanizeSourceFamily } from "../../_lib/presenters";
+import { humanizeNodeType, humanizeSourceFamily } from "../../_lib/presenters";
 
 type NodePageProps = {
   params: Promise<{ slug: string }>;
@@ -69,7 +69,7 @@ export default async function NodePage({ params }: NodePageProps) {
                 },
                 {
                   content: (
-                    <span>{profile.node.nodeType.replace(/_/g, " ")}</span>
+                    <span>{humanizeNodeType(profile.node.nodeType)}</span>
                   ),
                 },
                 {
@@ -117,7 +117,7 @@ export default async function NodePage({ params }: NodePageProps) {
               <dl className="mt-[var(--gg-space-4)]">
                 <KeyValue
                   label="Node type"
-                  value={profile.node.nodeType.replace(/_/g, " ")}
+                  value={humanizeNodeType(profile.node.nodeType)}
                 />
                 <KeyValue
                   label="Connected records"
diff --git a/apps/web/app/not-found.tsx b/apps/web/app/not-found.tsx
index 6a8c584..a236695 100644
--- a/apps/web/app/not-found.tsx
+++ b/apps/web/app/not-found.tsx
@@ -14,8 +14,9 @@ export default function NotFound() {
             This record isn&apos;t in the current snapshot.
           </h1>
           <p className="mt-[var(--gg-space-4)] text-[length:var(--gg-font-size-base)] leading-[var(--gg-font-line-height-body)] text-[var(--gg-color-semantic-text-secondary)]">
-            The sprint 1 prototype only includes the current ministry, current
-            portfolio mapping, and department-backed portfolio relationships.
+            The current snapshot covers the ministry, portfolio mapping,
+            departments, public entities, budget documents, and the VPSC
+            directory.
           </p>
           <div className="mt-[var(--gg-space-8)]">
             <Link
diff --git a/packages/ui/src/data-table-row-key.test.ts b/packages/ui/src/data-table-row-key.test.ts
new file mode 100644
index 0000000..99737ad
--- /dev/null
+++ b/packages/ui/src/data-table-row-key.test.ts
@@ -0,0 +1,67 @@
+import type { DataTableColumn } from "./data-table-sort";
+import { sortRows } from "./data-table-sort";
+import {
+  getDataTableRowKeyLookup,
+  getDataTableRowSignature,
+} from "./data-table-row-key";
+
+const columns = [
+  {
+    header: "Agency",
+    key: "agency",
+    sortable: true,
+  },
+  {
+    header: "Budget",
+    key: "budget",
+    sortable: true,
+  },
+] as const satisfies readonly DataTableColumn<{
+  agency: string;
+  budget: number | null;
+}>[];
+
+describe("getDataTableRowSignature", () => {
+  it("uses the configured column order to build a stable signature", () => {
+    expect(
+      getDataTableRowSignature(
+        {
+          agency: "Treasury and Finance",
+          budget: 8_300_000_000,
+        },
+        columns,
+      ),
+    ).toBe('[\"Treasury and Finance\",8300000000]');
+  });
+});
+
+describe("getDataTableRowKeyLookup", () => {
+  it("creates stable unique keys for duplicate rows after sorting", () => {
+    const rows = [
+      {
+        agency: "Transport and Planning",
+        budget: 16_700_000_000,
+      },
+      {
+        agency: "Transport and Planning",
+        budget: 16_700_000_000,
+      },
+      {
+        agency: "Treasury and Finance",
+        budget: 8_300_000_000,
+      },
+    ] as const;
+
+    const rowKeyLookup = getDataTableRowKeyLookup(rows, columns);
+    const sortedRows = sortRows(rows, {
+      columnKey: "agency",
+      direction: "asc",
+    });
+
+    expect(sortedRows.map((row) => rowKeyLookup.get(row))).toEqual([
+      '[\"Transport and Planning\",16700000000]::0',
+      '[\"Transport and Planning\",16700000000]::1',
+      '[\"Treasury and Finance\",8300000000]::0',
+    ]);
+  });
+});
diff --git a/packages/ui/src/data-table-row-key.ts b/packages/ui/src/data-table-row-key.ts
new file mode 100644
index 0000000..822d85b
--- /dev/null
+++ b/packages/ui/src/data-table-row-key.ts
@@ -0,0 +1,26 @@
+import type { DataTableColumn, DataTableRow } from "./data-table-sort";
+
+export function getDataTableRowSignature<Row extends DataTableRow>(
+  row: Row,
+  columns: readonly DataTableColumn<Row>[],
+): string {
+  return JSON.stringify(columns.map((column) => row[column.key] ?? null));
+}
+
+export function getDataTableRowKeyLookup<Row extends DataTableRow>(
+  rows: readonly Row[],
+  columns: readonly DataTableColumn<Row>[],
+): Map<Row, string> {
+  const signatureCounts = new Map<string, number>();
+  const rowKeyLookup = new Map<Row, string>();
+
+  for (const row of rows) {
+    const signature = getDataTableRowSignature(row, columns);
+    const occurrence = signatureCounts.get(signature) ?? 0;
+
+    signatureCounts.set(signature, occurrence + 1);
+    rowKeyLookup.set(row, `${signature}::${occurrence}`);
+  }
+
+  return rowKeyLookup;
+}
diff --git a/packages/ui/src/data-table.tsx b/packages/ui/src/data-table.tsx
index f02de03..e339533 100644
--- a/packages/ui/src/data-table.tsx
+++ b/packages/ui/src/data-table.tsx
@@ -10,6 +10,10 @@ import {
   type DataTableRow,
   type DataTableSortState,
 } from "./data-table-sort";
+import {
+  getDataTableRowKeyLookup,
+  getDataTableRowSignature,
+} from "./data-table-row-key";
 import { cn } from "./utils";
 
 type DataTableProps<Row extends DataTableRow> = HTMLAttributes<HTMLDivElement> & {
@@ -44,6 +48,7 @@ export function DataTable<Row extends DataTableRow>({
 }: DataTableProps<Row>) {
   const [sortState, setSortState] = useState<DataTableSortState<Row>>(null);
   const sortedRows = sortRows(rows, sortState);
+  const rowKeyLookup = getDataTableRowKeyLookup(rows, columns);
 
   return (
     <div
@@ -115,9 +120,11 @@ export function DataTable<Row extends DataTableRow>({
               </td>
             </tr>
           ) : (
-            sortedRows.map((row, rowIndex) => (
+            sortedRows.map((row) => (
               <tr
-                key={rowIndex}
+                key={
+                  rowKeyLookup.get(row) ?? getDataTableRowSignature(row, columns)
+                }
                 className="border-t border-[var(--gg-color-border)] first:border-t-0"
               >
                 {columns.map((column) => (