From 887c79ec865f74ca6e3a416a8266d87ca71413ce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Thu, 2 Jul 2026 00:00:37 +0200
Subject: [PATCH] refactor(ui): unify page headers and surface read failures

Add a PageHeader primitive (one H1 vocabulary, optional description,
back-link, and action slots) and route the hand-rolled headers through
it, so every module reads with the same title/subtitle rhythm and no
icon beside the page title. Mental Wellbeing gains a visible header.
Add a QueryErrorCard and wire the list surfaces so a failed read shows
a retry card instead of falling through to the empty state, and swap
their full-page spinners for skeletons that hold the layout.
---
 .../__tests__/dashboard-hero-wiring.test.ts   |   2 +-
 src/app/achievements/page.tsx                 |  31 ++-
 src/app/coach/conversations/page.tsx          |  15 +-
 src/app/labs/page.tsx                         | 122 ++++++------
 src/app/measurements/page.tsx                 |  27 +--
 src/app/mood/page.tsx                         |  76 ++++----
 src/app/notifications/page.tsx                |  35 ++--
 src/components/cycle/cycle-view.tsx           |  22 +--
 src/components/dashboard/dashboard-header.tsx | 182 +++++++++---------
 src/components/illness/illness-view.tsx       | 104 ++++------
 src/components/labs/lab-list.tsx              |  12 +-
 .../measurements/measurement-list.tsx         |  14 +-
 .../mental-health/mental-wellbeing.tsx        |  15 +-
 src/components/mood/mood-list.tsx             |  32 ++-
 src/components/ui/page-header.tsx             |  43 +++++
 src/components/ui/query-error-card.tsx        |  59 ++++++
 16 files changed, 413 insertions(+), 378 deletions(-)
 create mode 100644 src/components/ui/page-header.tsx
 create mode 100644 src/components/ui/query-error-card.tsx

diff --git a/src/app/__tests__/dashboard-hero-wiring.test.ts b/src/app/__tests__/dashboard-hero-wiring.test.ts
index 898830436..c5f562cd0 100644
--- a/src/app/__tests__/dashboard-hero-wiring.test.ts
+++ b/src/app/__tests__/dashboard-hero-wiring.test.ts
@@ -74,7 +74,7 @@ describe("dashboard hero — header handoff", () => {
     // prop gates the paragraph, and the `min-h-5` line-box reservation
     // keeps the header stable through the post-hydration name swap.
     expect(header).toContain("showGreeting");
-    expect(header).toMatch(/\{showGreeting\s*\?/);
+    expect(header).toMatch(/\{\s*showGreeting\s*\?/);
     expect(header).toContain("min-h-5");
     expect(header).toContain('data-slot="dashboard-header-greeting"');
   });
diff --git a/src/app/achievements/page.tsx b/src/app/achievements/page.tsx
index 40a60c63f..6e4c2fae1 100644
--- a/src/app/achievements/page.tsx
+++ b/src/app/achievements/page.tsx
@@ -32,6 +32,7 @@ import {
 import { Progress } from "@/components/ui/progress";
 import { Badge } from "@/components/ui/badge";
 import { EmptyState } from "@/components/ui/empty-state";
+import { PageHeader } from "@/components/ui/page-header";
 import { useAuth } from "@/hooks/use-auth";
 import { useTranslations } from "@/lib/i18n/context";
 import { formatDate } from "@/lib/format";
@@ -293,12 +294,10 @@ export default function AchievementsPage() {
   if (!isAuthenticated) {
     return (
       <div className="space-y-6">
-        <h1 className="text-2xl font-bold tracking-tight">
-          {t("achievements.title")}
-        </h1>
-        <p className="text-muted-foreground text-sm">
-          {t("achievements.loginRequired")}
-        </p>
+        <PageHeader
+          title={t("achievements.title")}
+          description={t("achievements.loginRequired")}
+        />
       </div>
     );
   }
@@ -313,20 +312,14 @@ export default function AchievementsPage() {
 
   return (
     <div className="space-y-6">
-      <div className="flex items-start justify-between gap-3">
-        <div className="min-w-0">
-          <h1
-            data-tour-id="achievements-hero"
-            className="text-2xl font-bold tracking-tight"
-          >
+      <PageHeader
+        title={
+          <span data-tour-id="achievements-hero">
             {t("achievements.title")}
-          </h1>
-          <p className="text-muted-foreground text-sm">
-            {t("achievements.subtitle")}
-          </p>
-        </div>
-        <div className="flex shrink-0 items-center gap-2"></div>
-      </div>
+          </span>
+        }
+        description={t("achievements.subtitle")}
+      />
 
       <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
         <div className="bg-card border-border flex min-h-34 flex-col justify-between rounded-xl border p-5">
diff --git a/src/app/coach/conversations/page.tsx b/src/app/coach/conversations/page.tsx
index dfa955015..c2677c2d7 100644
--- a/src/app/coach/conversations/page.tsx
+++ b/src/app/coach/conversations/page.tsx
@@ -6,6 +6,7 @@ import { MessagesSquare, Search, Trash2 } from "lucide-react";
 
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
+import { PageHeader } from "@/components/ui/page-header";
 import { COACH_SCROLLBAR } from "@/components/insights/coach-panel/message-thread";
 import {
   useCoachConversations,
@@ -122,13 +123,13 @@ function CoachConversationsBody() {
   return (
     <div className="mx-auto flex h-full min-h-0 w-full max-w-screen-xl flex-col gap-4 px-4 pt-6 pb-4 md:px-6">
       <header className="flex flex-col gap-3">
-        <h1
-          data-slot="coach-conversations-heading"
-          className="text-foreground flex items-center gap-2 text-lg font-semibold"
-        >
-          <MessagesSquare className="size-5" aria-hidden="true" />
-          {t("insights.coach.historyTitle")}
-        </h1>
+        <PageHeader
+          title={
+            <span data-slot="coach-conversations-heading">
+              {t("insights.coach.historyTitle")}
+            </span>
+          }
+        />
         <div className="relative">
           <Search
             aria-hidden="true"
diff --git a/src/app/labs/page.tsx b/src/app/labs/page.tsx
index 3397db3a3..20f64999c 100644
--- a/src/app/labs/page.tsx
+++ b/src/app/labs/page.tsx
@@ -17,6 +17,7 @@ import {
   DropdownMenuItem,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
+import { PageHeader } from "@/components/ui/page-header";
 import { PullToRefreshIndicator } from "@/components/ui/pull-to-refresh-indicator";
 import { ResponsiveSheet } from "@/components/ui/responsive-sheet";
 import { useAuth } from "@/hooks/use-auth";
@@ -66,73 +67,66 @@ export default function LabsPage() {
   return (
     <div className="space-y-6">
       <PullToRefreshIndicator {...pull} />
-      <div className="flex items-start justify-between gap-3">
-        <div className="min-w-0">
-          <h1
-            data-tour-id="labs-hero"
-            className="text-2xl font-bold tracking-tight"
-          >
-            {t("labs.title")}
-          </h1>
-          <p className="text-muted-foreground text-xs sm:text-sm">
-            {t("labs.subtitle")}
-          </p>
-        </div>
-        <div className="flex shrink-0 items-center gap-2">
-          {/* v1.18.6 (MOD-01) — the wrench is the module's customize entry
-              point, left of the primary Add and linking to the Labs settings
-              page (view, sort order, biomarker CRUD + reorder). Mirrors the
-              medication page header's wrench glyph + slot + 44px tap floor. */}
-          <Button
-            asChild
-            variant="ghost"
-            size="icon"
-            className="min-h-11 min-w-11 sm:min-h-9 sm:min-w-9"
-          >
-            <Link
-              href="/settings/layout/labs"
-              aria-label={t("labs.customize")}
-              title={t("labs.customize")}
-            >
-              <Wrench className="h-4 w-4" aria-hidden="true" />
-            </Link>
-          </Button>
-          {/* v1.18.10 — the "Add" action is a CHOICE when scanning is
-              available: scan a document (OCR) or add a value by hand. The scan
-              option only appears when the capability probe reports a usable
-              mode (vision, or local OCR opted-in for text-only providers), so
-              the surface stays simple for everyone else. When scanning is
-              unavailable, Add opens the manual form directly. */}
-          {ocrCapability.data?.available ? (
-            <DropdownMenu>
-              <DropdownMenuTrigger asChild>
-                <Button className="min-h-11 sm:min-h-9">
-                  <Plus className="h-4 w-4" />
-                  {t("common.add")}
-                </Button>
-              </DropdownMenuTrigger>
-              <DropdownMenuContent align="end">
-                <DropdownMenuItem onSelect={() => setScanOpen(true)}>
-                  <ScanLine className="h-4 w-4" aria-hidden="true" />
-                  {t("labs.ocr.addScan")}
-                </DropdownMenuItem>
-                <DropdownMenuItem onSelect={() => setDialogOpen(true)}>
-                  <Pencil className="h-4 w-4" aria-hidden="true" />
-                  {t("labs.ocr.addManual")}
-                </DropdownMenuItem>
-              </DropdownMenuContent>
-            </DropdownMenu>
-          ) : (
+      <PageHeader
+        title={<span data-tour-id="labs-hero">{t("labs.title")}</span>}
+        description={t("labs.subtitle")}
+        actions={
+          <>
+            {/* v1.18.6 (MOD-01) — the wrench is the module's customize entry
+                point, left of the primary Add and linking to the Labs settings
+                page (view, sort order, biomarker CRUD + reorder). Mirrors the
+                medication page header's wrench glyph + slot + 44px tap floor. */}
             <Button
-              onClick={() => setDialogOpen(true)}
-              className="min-h-11 sm:min-h-9"
+              asChild
+              variant="ghost"
+              size="icon"
+              className="min-h-11 min-w-11 sm:min-h-9 sm:min-w-9"
             >
-              <Plus className="h-4 w-4" />
-              {t("common.add")}
+              <Link
+                href="/settings/layout/labs"
+                aria-label={t("labs.customize")}
+                title={t("labs.customize")}
+              >
+                <Wrench className="h-4 w-4" aria-hidden="true" />
+              </Link>
             </Button>
-          )}
-        </div>
-      </div>
+            {/* v1.18.10 — the "Add" action is a CHOICE when scanning is
+                available: scan a document (OCR) or add a value by hand. The scan
+                option only appears when the capability probe reports a usable
+                mode (vision, or local OCR opted-in for text-only providers), so
+                the surface stays simple for everyone else. When scanning is
+                unavailable, Add opens the manual form directly. */}
+            {ocrCapability.data?.available ? (
+              <DropdownMenu>
+                <DropdownMenuTrigger asChild>
+                  <Button className="min-h-11 sm:min-h-9">
+                    <Plus className="h-4 w-4" />
+                    {t("common.add")}
+                  </Button>
+                </DropdownMenuTrigger>
+                <DropdownMenuContent align="end">
+                  <DropdownMenuItem onSelect={() => setScanOpen(true)}>
+                    <ScanLine className="h-4 w-4" aria-hidden="true" />
+                    {t("labs.ocr.addScan")}
+                  </DropdownMenuItem>
+                  <DropdownMenuItem onSelect={() => setDialogOpen(true)}>
+                    <Pencil className="h-4 w-4" aria-hidden="true" />
+                    {t("labs.ocr.addManual")}
+                  </DropdownMenuItem>
+                </DropdownMenuContent>
+              </DropdownMenu>
+            ) : (
+              <Button
+                onClick={() => setDialogOpen(true)}
+                className="min-h-11 sm:min-h-9"
+              >
+                <Plus className="h-4 w-4" />
+                {t("common.add")}
+              </Button>
+            )}
+          </>
+        }
+      />
 
       <ResponsiveSheet
         open={dialogOpen}
diff --git a/src/app/measurements/page.tsx b/src/app/measurements/page.tsx
index cb506e45e..6d6aed90d 100644
--- a/src/app/measurements/page.tsx
+++ b/src/app/measurements/page.tsx
@@ -13,6 +13,7 @@ import { MeasurementList } from "@/components/measurements/measurement-list";
 import { CustomMetricList } from "@/components/custom-metrics/custom-metric-list";
 import { MEASUREMENT_TYPE_LABEL_KEYS } from "@/components/measurements/measurement-list-meta";
 import { Button } from "@/components/ui/button";
+import { PageHeader } from "@/components/ui/page-header";
 import { PullToRefreshIndicator } from "@/components/ui/pull-to-refresh-indicator";
 import { ResponsiveSheet } from "@/components/ui/responsive-sheet";
 import { Plus, Loader2 } from "lucide-react";
@@ -125,22 +126,14 @@ export default function MeasurementsPage() {
   return (
     <div className="space-y-6">
       <PullToRefreshIndicator {...pull} />
-      <div className="flex items-center justify-between">
-        <div className="min-w-0">
-          <h1
-            data-tour-id="measurements-hero"
-            className="text-2xl font-bold tracking-tight"
-          >
+      <PageHeader
+        title={
+          <span data-tour-id="measurements-hero">
             {t("measurements.title")}
-          </h1>
-          {/* v1.4.34 IW-G — subtitle now stays visible on mobile so
-              the H1 isn't an unframed label. `text-xs sm:text-sm`
-              preserves the desktop hierarchy. */}
-          <p className="text-muted-foreground truncate text-xs sm:text-sm">
-            {t("measurements.subtitle")}
-          </p>
-        </div>
-        <div className="flex shrink-0 items-center gap-2">
+          </span>
+        }
+        description={t("measurements.subtitle")}
+        actions={
           <Button
             className="min-h-11 sm:min-h-9"
             onClick={() => setDialogOpen(true)}
@@ -148,8 +141,8 @@ export default function MeasurementsPage() {
             <Plus className="h-4 w-4" />
             {t("measurements.addMeasurement")}
           </Button>
-        </div>
-      </div>
+        }
+      />
 
       <ResponsiveSheet
         open={dialogOpen}
diff --git a/src/app/mood/page.tsx b/src/app/mood/page.tsx
index 9f63ea3c6..231eae7f9 100644
--- a/src/app/mood/page.tsx
+++ b/src/app/mood/page.tsx
@@ -9,6 +9,7 @@ import { usePullToRefresh } from "@/hooks/use-pull-to-refresh";
 import { MoodForm } from "@/components/mood/mood-form";
 import { MoodList } from "@/components/mood/mood-list";
 import { Button } from "@/components/ui/button";
+import { PageHeader } from "@/components/ui/page-header";
 import { PullToRefreshIndicator } from "@/components/ui/pull-to-refresh-indicator";
 import { ResponsiveSheet } from "@/components/ui/responsive-sheet";
 import { Plus, Loader2, Wrench } from "lucide-react";
@@ -63,49 +64,40 @@ export default function MoodPage() {
   return (
     <div className="space-y-6">
       <PullToRefreshIndicator {...pull} />
-      <div className="flex items-center justify-between">
-        <div className="min-w-0">
-          <h1
-            data-tour-id="mood-hero"
-            className="text-2xl font-bold tracking-tight"
-          >
-            {t("mood.title")}
-          </h1>
-          {/* v1.4.34 IW-G — subtitle stays visible on mobile so the
-              H1 isn't an unframed label. */}
-          <p className="text-muted-foreground truncate text-xs sm:text-sm">
-            {t("mood.subtitle")}
-          </p>
-        </div>
-        <div className="flex shrink-0 items-center gap-2">
-          {/* v1.17 — the wrench is the one customize entry point: it
-              links to /settings/mood, which owns the tag groups, custom
-              tags, visibility, and picker order. Same glyph, slot (left
-              of the add button) and responsive 44-px mobile tap floor
-              as the medications header. */}
-          <Button
-            asChild
-            variant="ghost"
-            size="icon"
-            className="min-h-11 min-w-11 sm:min-h-9 sm:min-w-9"
-          >
-            <Link
-              href="/settings/layout/mood"
-              aria-label={t("mood.customize")}
-              title={t("mood.customize")}
+      <PageHeader
+        title={<span data-tour-id="mood-hero">{t("mood.title")}</span>}
+        description={t("mood.subtitle")}
+        actions={
+          <>
+            {/* v1.17 — the wrench is the one customize entry point: it
+                links to /settings/mood, which owns the tag groups, custom
+                tags, visibility, and picker order. Same glyph, slot (left
+                of the add button) and responsive 44-px mobile tap floor
+                as the medications header. */}
+            <Button
+              asChild
+              variant="ghost"
+              size="icon"
+              className="min-h-11 min-w-11 sm:min-h-9 sm:min-w-9"
             >
-              <Wrench className="h-4 w-4" aria-hidden="true" />
-            </Link>
-          </Button>
-          <Button
-            onClick={() => setDialogOpen(true)}
-            className="min-h-11 sm:min-h-9"
-          >
-            <Plus className="h-4 w-4" />
-            {t("mood.addEntry")}
-          </Button>
-        </div>
-      </div>
+              <Link
+                href="/settings/layout/mood"
+                aria-label={t("mood.customize")}
+                title={t("mood.customize")}
+              >
+                <Wrench className="h-4 w-4" aria-hidden="true" />
+              </Link>
+            </Button>
+            <Button
+              onClick={() => setDialogOpen(true)}
+              className="min-h-11 sm:min-h-9"
+            >
+              <Plus className="h-4 w-4" />
+              {t("mood.addEntry")}
+            </Button>
+          </>
+        }
+      />
 
       <ResponsiveSheet
         open={dialogOpen}
diff --git a/src/app/notifications/page.tsx b/src/app/notifications/page.tsx
index c36f72a8f..66113ea13 100644
--- a/src/app/notifications/page.tsx
+++ b/src/app/notifications/page.tsx
@@ -6,6 +6,7 @@ import { useTranslations } from "@/lib/i18n/context";
 import { Switch } from "@/components/ui/switch";
 import { Label } from "@/components/ui/label";
 import { Button } from "@/components/ui/button";
+import { PageHeader } from "@/components/ui/page-header";
 import Link from "next/link";
 import { Bell, Loader2, Settings, AlertCircle } from "lucide-react";
 import {
@@ -129,12 +130,10 @@ export default function NotificationsPage() {
   if (!isAuthenticated) {
     return (
       <div className="space-y-6">
-        <h1 className="text-2xl font-bold tracking-tight">
-          {t("notifications.title")}
-        </h1>
-        <p className="text-muted-foreground text-sm">
-          {t("notifications.loginRequired")}
-        </p>
+        <PageHeader
+          title={t("notifications.title")}
+          description={t("notifications.loginRequired")}
+        />
       </div>
     );
   }
@@ -146,14 +145,10 @@ export default function NotificationsPage() {
   if (isError) {
     return (
       <div className="space-y-6">
-        <div>
-          <h1 className="text-2xl font-bold tracking-tight">
-            {t("notifications.title")}
-          </h1>
-          <p className="text-muted-foreground text-sm">
-            {t("notifications.subtitle")}
-          </p>
-        </div>
+        <PageHeader
+          title={t("notifications.title")}
+          description={t("notifications.subtitle")}
+        />
         <div
           role="alert"
           className="border-destructive/40 bg-destructive/10 text-destructive rounded-lg border p-4 text-sm"
@@ -168,14 +163,10 @@ export default function NotificationsPage() {
   if (activeChannels.length === 0) {
     return (
       <div className="space-y-6">
-        <div>
-          <h1 className="text-2xl font-bold tracking-tight">
-            {t("notifications.title")}
-          </h1>
-          <p className="text-muted-foreground text-sm">
-            {t("notifications.subtitle")}
-          </p>
-        </div>
+        <PageHeader
+          title={t("notifications.title")}
+          description={t("notifications.subtitle")}
+        />
         <div className="bg-card border-border max-w-2xl rounded-xl border p-6">
           <div className="flex flex-col items-center gap-4 py-8 text-center">
             <Bell className="text-muted-foreground h-12 w-12" />
diff --git a/src/components/cycle/cycle-view.tsx b/src/components/cycle/cycle-view.tsx
index 7489fd3c1..7016b61cd 100644
--- a/src/components/cycle/cycle-view.tsx
+++ b/src/components/cycle/cycle-view.tsx
@@ -6,6 +6,7 @@ import { Loader2, Plus, RefreshCw, Sparkles } from "lucide-react";
 
 import { Button } from "@/components/ui/button";
 import { Card, CardContent } from "@/components/ui/card";
+import { PageHeader } from "@/components/ui/page-header";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import { useTranslations } from "@/lib/i18n/context";
 import { cn } from "@/lib/utils";
@@ -125,19 +126,10 @@ export function CycleView() {
 
   return (
     <div className="space-y-6">
-      <div className="flex items-start justify-between gap-3">
-        <div className="min-w-0">
-          <h1
-            data-tour-id="cycle-hero"
-            className="text-2xl font-bold tracking-tight"
-          >
-            {t("cycle.title")}
-          </h1>
-          <p className="text-muted-foreground text-xs sm:text-sm">
-            {t("cycle.subtitle")}
-          </p>
-        </div>
-        <div className="flex shrink-0 items-center gap-2">
+      <PageHeader
+        title={<span data-tour-id="cycle-hero">{t("cycle.title")}</span>}
+        description={t("cycle.subtitle")}
+        actions={
           <Button
             onClick={() => openSheet(today)}
             className="min-h-11 sm:min-h-9"
@@ -145,8 +137,8 @@ export function CycleView() {
             <Plus className="h-4 w-4" />
             {t("cycle.logToday")}
           </Button>
-        </div>
-      </div>
+        }
+      />
 
       {/* Desktop: ring (left) + tabs (right). Single column below lg. */}
       <div className="grid gap-6 lg:grid-cols-[minmax(0,22rem)_minmax(0,1fr)] lg:items-start">
diff --git a/src/components/dashboard/dashboard-header.tsx b/src/components/dashboard/dashboard-header.tsx
index 72d0b7540..7d686cac7 100644
--- a/src/components/dashboard/dashboard-header.tsx
+++ b/src/components/dashboard/dashboard-header.tsx
@@ -22,11 +22,11 @@ import {
   DropdownMenuItem,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
+import { PageHeader } from "@/components/ui/page-header";
 import { useTranslations } from "@/lib/i18n/context";
 import { useAuth } from "@/hooks/use-auth";
 import { useMounted } from "@/hooks/use-mounted";
 import { getHourForTimeZone } from "@/components/dashboard/range-display";
-import { cn } from "@/lib/utils";
 import type { QuickEntryDialog } from "@/components/dashboard/quick-entry-sheets";
 
 export function DashboardHeader({
@@ -68,106 +68,102 @@ export function DashboardHeader({
       : t("dashboard.welcomeBack", { greeting: timeGreeting });
 
   return (
-    /* With the greeting the title block is two lines on narrow
-       viewports: centre the buttons against it on mobile, top-align on
-       sm+ (the pre-hero posture). Without the greeting the single-line
-       centre alignment stands. */
-    <div
-      className={cn(
-        "flex items-center justify-between gap-4",
-        showGreeting && "sm:items-start",
-      )}
-    >
-      <div className="min-w-0">
-        <h1 className="text-2xl font-bold tracking-tight">
-          {t("dashboard.title")}
-        </h1>
-        {showGreeting ? (
+    <PageHeader
+      title={t("dashboard.title")}
+      description={
+        showGreeting ? (
           /* `min-h-5` reserves the greeting's line box from the SSR
              pass on: the text personalises (name appended) on the first
              client re-render after hydration, and the reserved line
              keeps the header from collapsing/growing around that swap. */
-          <p
+          <span
             data-slot="dashboard-header-greeting"
-            className="text-muted-foreground mt-1 min-h-5 truncate text-sm"
+            className="block min-h-5 truncate"
           >
             {welcomeText}
-          </p>
-        ) : null}
-      </div>
-      <div className="flex shrink-0 items-center gap-2">
-        {/* Customize shortcut to the dashboard-customization settings
-            (the tile/layout editor at /settings/dashboard). Sits to
-            the left of the add button as a monochrome ghost icon, with
-            a `min-h-11 min-w-11` mobile floor so it meets the 44 px
-            touch-target contract the add button also honours, shrinking
-            back to the 40 px icon footprint on sm+. */}
-        <Button
-          asChild
-          variant="ghost"
-          size="icon"
-          className="min-h-11 min-w-11 sm:min-h-9 sm:min-w-9"
-          data-testid="dashboard-customize-shortcut"
-        >
-          <Link
-            href="/settings/layout/dashboard"
-            aria-label={t("dashboard.customizeDashboard")}
-            title={t("dashboard.customizeDashboard")}
+          </span>
+        ) : undefined
+      }
+      actions={
+        <>
+          {/* Customize shortcut to the dashboard-customization settings
+              (the tile/layout editor at /settings/dashboard). Sits to
+              the left of the add button as a monochrome ghost icon, with
+              a `min-h-11 min-w-11` mobile floor so it meets the 44 px
+              touch-target contract the add button also honours, shrinking
+              back to the 40 px icon footprint on sm+. */}
+          <Button
+            asChild
+            variant="ghost"
+            size="icon"
+            className="min-h-11 min-w-11 sm:min-h-9 sm:min-w-9"
+            data-testid="dashboard-customize-shortcut"
           >
-            <Wrench className="h-4 w-4" aria-hidden="true" />
-          </Link>
-        </Button>
-        <DropdownMenu>
-          <DropdownMenuTrigger asChild>
-            {/* v1.4.33 maintainer-item-7 — restore proportional sizing
-                across viewports. The v1.4.27 fix pinned a `size="sm"
-                min-h-11` combo to hit WCAG 2.5.5's 44 px touch-target
-                contract on mobile, but `size="sm"` is h-8 (32 px) and
-                the `min-h-11` override stretched the cap vertically
-                while keeping the small horizontal padding — the
-                button read as klobig on Pixel 5. Switch to
-                `size="default"` (h-10 = 40 px) on mobile with a
-                responsive `min-h-11 sm:min-h-9` so the button is
-                44 px tall under finger pressure and shrinks back to
-                the desktop-friendly 36 px on `sm:` upwards. The icon
-                + label keep the same visual contract. */}
-            <Button
-              size="default"
-              className="min-h-11 sm:min-h-9"
-              data-tour-id="dashboard-quick-add"
+            <Link
+              href="/settings/layout/dashboard"
+              aria-label={t("dashboard.customizeDashboard")}
+              title={t("dashboard.customizeDashboard")}
             >
-              <Plus className="h-4 w-4" />
-              {t("common.add")}
-            </Button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent align="end" className="max-w-[calc(100vw-2rem)]">
-            {/* Menu items must each carry a self-contained verb-phrase
-                ("Log measurement", "Log mood") — the trigger above already
-                says "Add", and the icon is `aria-hidden`, so the visible
-                text is the only thing distinguishing the rows. v1.4.15
-                phase-A3 fix #1 hardened this with a unit guard at
-                `src/app/__tests__/quick-add-labels.test.ts` — both labels
-                must differ from each other AND from `common.add`. */}
-            <DropdownMenuItem onClick={() => onQuickEntry("measurement")}>
-              <Activity className="mr-2 h-4 w-4" aria-hidden="true" />
-              {t("dashboard.quickAddMeasurement")}
-            </DropdownMenuItem>
-            <DropdownMenuItem onClick={() => onQuickEntry("mood")}>
-              <Waves className="mr-2 h-4 w-4" aria-hidden="true" />
-              {t("dashboard.quickAddMood")}
-            </DropdownMenuItem>
-            {/* v1.4.37 W7b — third quick-add row: medication intake.
-                Same Sheet-on-mobile / Dialog-on-desktop primitive as
-                the other two; the menu label is a self-contained
-                verb-phrase so it doesn't collide with the trigger or
-                the sibling rows (cf. quick-add-labels.test.ts). */}
-            <DropdownMenuItem onClick={() => onQuickEntry("medicationIntake")}>
-              <Pill className="mr-2 h-4 w-4" aria-hidden="true" />
-              {t("dashboard.quickAddMedicationIntake")}
-            </DropdownMenuItem>
-          </DropdownMenuContent>
-        </DropdownMenu>
-      </div>
-    </div>
+              <Wrench className="h-4 w-4" aria-hidden="true" />
+            </Link>
+          </Button>
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              {/* v1.4.33 maintainer-item-7 — restore proportional sizing
+                  across viewports. The v1.4.27 fix pinned a `size="sm"
+                  min-h-11` combo to hit WCAG 2.5.5's 44 px touch-target
+                  contract on mobile, but `size="sm"` is h-8 (32 px) and
+                  the `min-h-11` override stretched the cap vertically
+                  while keeping the small horizontal padding — the
+                  button read as klobig on Pixel 5. Switch to
+                  `size="default"` (h-10 = 40 px) on mobile with a
+                  responsive `min-h-11 sm:min-h-9` so the button is
+                  44 px tall under finger pressure and shrinks back to
+                  the desktop-friendly 36 px on `sm:` upwards. The icon
+                  + label keep the same visual contract. */}
+              <Button
+                size="default"
+                className="min-h-11 sm:min-h-9"
+                data-tour-id="dashboard-quick-add"
+              >
+                <Plus className="h-4 w-4" />
+                {t("common.add")}
+              </Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent
+              align="end"
+              className="max-w-[calc(100vw-2rem)]"
+            >
+              {/* Menu items must each carry a self-contained verb-phrase
+                  ("Log measurement", "Log mood") — the trigger above already
+                  says "Add", and the icon is `aria-hidden`, so the visible
+                  text is the only thing distinguishing the rows. v1.4.15
+                  phase-A3 fix #1 hardened this with a unit guard at
+                  `src/app/__tests__/quick-add-labels.test.ts` — both labels
+                  must differ from each other AND from `common.add`. */}
+              <DropdownMenuItem onClick={() => onQuickEntry("measurement")}>
+                <Activity className="mr-2 h-4 w-4" aria-hidden="true" />
+                {t("dashboard.quickAddMeasurement")}
+              </DropdownMenuItem>
+              <DropdownMenuItem onClick={() => onQuickEntry("mood")}>
+                <Waves className="mr-2 h-4 w-4" aria-hidden="true" />
+                {t("dashboard.quickAddMood")}
+              </DropdownMenuItem>
+              {/* v1.4.37 W7b — third quick-add row: medication intake.
+                  Same Sheet-on-mobile / Dialog-on-desktop primitive as
+                  the other two; the menu label is a self-contained
+                  verb-phrase so it doesn't collide with the trigger or
+                  the sibling rows (cf. quick-add-labels.test.ts). */}
+              <DropdownMenuItem
+                onClick={() => onQuickEntry("medicationIntake")}
+              >
+                <Pill className="mr-2 h-4 w-4" aria-hidden="true" />
+                {t("dashboard.quickAddMedicationIntake")}
+              </DropdownMenuItem>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        </>
+      }
+    />
   );
 }
diff --git a/src/components/illness/illness-view.tsx b/src/components/illness/illness-view.tsx
index 8f8d16772..d786c6aeb 100644
--- a/src/components/illness/illness-view.tsx
+++ b/src/components/illness/illness-view.tsx
@@ -17,13 +17,7 @@
  */
 import { useId, useMemo, useState } from "react";
 import Link from "next/link";
-import {
-  ChevronDown,
-  Plus,
-  RefreshCw,
-  Stethoscope,
-  Wrench,
-} from "lucide-react";
+import { ChevronDown, Plus, Stethoscope, Wrench } from "lucide-react";
 
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
@@ -35,6 +29,8 @@ import {
   CardTitle,
 } from "@/components/ui/card";
 import { EmptyState } from "@/components/ui/empty-state";
+import { PageHeader } from "@/components/ui/page-header";
+import { QueryErrorCard } from "@/components/ui/query-error-card";
 import { Skeleton } from "@/components/ui/skeleton";
 import { cn } from "@/lib/utils";
 import { useTranslations, useFormatters } from "@/lib/i18n/context";
@@ -379,46 +375,39 @@ export function IllnessView() {
 
   return (
     <div className="space-y-6">
-      <div className="flex items-start justify-between gap-3">
-        <div className="min-w-0">
-          <h1
-            data-tour-id="illness-hero"
-            className="text-2xl font-bold tracking-tight"
-          >
-            {t("illness.title")}
-          </h1>
-          <p className="text-muted-foreground text-xs sm:text-sm">
-            {t("illness.subtitle")}
-          </p>
-        </div>
-        <div className="flex shrink-0 items-center gap-2">
-          {/* v1.18.6 (MOD-01) — wrench left of the primary Add, linking to the
-              Illness settings page (view + reorder). */}
-          <Button
-            asChild
-            variant="ghost"
-            size="icon"
-            className="min-h-11 min-w-11 sm:min-h-9 sm:min-w-9"
-          >
-            <Link
-              href="/settings/layout/illness"
-              aria-label={t("illness.customize")}
-              title={t("illness.customize")}
+      <PageHeader
+        title={<span data-tour-id="illness-hero">{t("illness.title")}</span>}
+        description={t("illness.subtitle")}
+        actions={
+          <>
+            {/* v1.18.6 (MOD-01) — wrench left of the primary Add, linking to the
+                Illness settings page (view + reorder). */}
+            <Button
+              asChild
+              variant="ghost"
+              size="icon"
+              className="min-h-11 min-w-11 sm:min-h-9 sm:min-w-9"
             >
-              <Wrench className="h-4 w-4" aria-hidden="true" />
-            </Link>
-          </Button>
-          {/* v1.18.6 (MOD-02) — the add button reads "hinzufügen" like every
-              other module, not the bespoke "neue Episode". */}
-          <Button
-            onClick={() => setNewOpen(true)}
-            className="min-h-11 sm:min-h-9"
-          >
-            <Plus className="h-4 w-4" />
-            {t("common.add")}
-          </Button>
-        </div>
-      </div>
+              <Link
+                href="/settings/layout/illness"
+                aria-label={t("illness.customize")}
+                title={t("illness.customize")}
+              >
+                <Wrench className="h-4 w-4" aria-hidden="true" />
+              </Link>
+            </Button>
+            {/* v1.18.6 (MOD-02) — the add button reads "hinzufügen" like every
+                other module, not the bespoke "neue Episode". */}
+            <Button
+              onClick={() => setNewOpen(true)}
+              className="min-h-11 sm:min-h-9"
+            >
+              <Plus className="h-4 w-4" />
+              {t("common.add")}
+            </Button>
+          </>
+        }
+      />
 
       {/* v1.18.6 (DISC-01) — the per-page medical disclaimer line is removed;
           the one-time acknowledgment now lives at onboarding and the legal
@@ -430,23 +419,12 @@ export function IllnessView() {
           <Skeleton className="h-32 w-full" />
         </div>
       ) : isError ? (
-        <div
-          role="alert"
-          data-slot="illness-list-error"
-          className="text-muted-foreground flex flex-col items-start gap-3 py-8 text-sm sm:flex-row sm:items-center sm:justify-between"
-        >
-          <span>{t("illness.listLoadError")}</span>
-          <Button
-            type="button"
-            size="sm"
-            variant="outline"
-            onClick={() => void refetch()}
-            className="gap-1.5"
-          >
-            <RefreshCw className="h-3.5 w-3.5" aria-hidden="true" />
-            <span>{t("common.retry")}</span>
-          </Button>
-        </div>
+        // A read failure is NOT an empty journal — surface the error + Retry so
+        // an outage never reads as "no episodes yet".
+        <QueryErrorCard
+          title={t("illness.listLoadError")}
+          onRetry={() => void refetch()}
+        />
       ) : hasEpisodes ? (
         <>
           {/* Retrospective summary sits above the list so a long history
diff --git a/src/components/labs/lab-list.tsx b/src/components/labs/lab-list.tsx
index a1e38d77e..372b2a7af 100644
--- a/src/components/labs/lab-list.tsx
+++ b/src/components/labs/lab-list.tsx
@@ -9,6 +9,7 @@ import { MedicationCardHeader } from "@/components/medications/medication-card-h
 import { Button } from "@/components/ui/button";
 import { Card, CardContent } from "@/components/ui/card";
 import { EmptyState } from "@/components/ui/empty-state";
+import { QueryErrorCard } from "@/components/ui/query-error-card";
 import { Skeleton } from "@/components/ui/skeleton";
 import { apiGet } from "@/lib/api/api-fetch";
 import { formatDate } from "@/lib/format";
@@ -93,7 +94,7 @@ export function LabList({ onAddFirst }: { onAddFirst?: () => void } = {}) {
     sortDir: "desc",
   });
 
-  const { data, isLoading, isError } = useQuery({
+  const { data, isLoading, isError, refetch } = useQuery({
     queryKey: listKey,
     queryFn: () =>
       apiGet<LabResultListResponse>("/api/labs?limit=500&sortDir=desc"),
@@ -149,10 +150,13 @@ export function LabList({ onAddFirst }: { onAddFirst?: () => void } = {}) {
   }
 
   if (isError) {
+    // A read failure is NOT an empty list — surface the error + Retry so an
+    // outage never reads as "you have no lab results".
     return (
-      <p role="alert" className="text-destructive py-8 text-center text-sm">
-        {t("labs.loadError")}
-      </p>
+      <QueryErrorCard
+        title={t("labs.loadError")}
+        onRetry={() => void refetch()}
+      />
     );
   }
 
diff --git a/src/components/measurements/measurement-list.tsx b/src/components/measurements/measurement-list.tsx
index 8d7f918eb..0c11a5d80 100644
--- a/src/components/measurements/measurement-list.tsx
+++ b/src/components/measurements/measurement-list.tsx
@@ -6,6 +6,8 @@ import { useAuth } from "@/hooks/use-auth";
 import { Button } from "@/components/ui/button";
 import { Badge } from "@/components/ui/badge";
 import { EmptyState } from "@/components/ui/empty-state";
+import { QueryErrorCard } from "@/components/ui/query-error-card";
+import { Skeleton } from "@/components/ui/skeleton";
 import { ListRow } from "@/components/ui/list-row";
 import {
   FilterBar,
@@ -461,7 +463,7 @@ export function MeasurementList({
       ? "groupBy=day"
       : "raw";
 
-  const { data, isLoading } = useQuery({
+  const { data, isLoading, isError, refetch } = useQuery({
     queryKey: queryKeys.measurementsList({
       type: typeFilter === "ALL" ? undefined : typeFilter,
       sourceEq,
@@ -825,9 +827,15 @@ export function MeasurementList({
         )}
 
         {isLoading ? (
-          <div className="flex h-32 items-center justify-center">
-            <Loader2 className="text-primary h-6 w-6 animate-spin motion-reduce:animate-none" />
+          <div className="space-y-2" data-slot="measurement-list-loading">
+            {Array.from({ length: 6 }, (_, i) => (
+              <Skeleton key={i} className="h-14 w-full rounded-lg" />
+            ))}
           </div>
+        ) : isError ? (
+          // A read failure is NOT an empty list — surface the error + Retry so
+          // an outage never reads as "you have no measurements".
+          <QueryErrorCard onRetry={() => void refetch()} />
         ) : !data?.measurements?.length ? (
           // v1.4.15 phase-C5: replaces the bare-text empty rectangle.
           // Filter-aware copy distinguishes brand-new accounts ("no
diff --git a/src/components/mental-health/mental-wellbeing.tsx b/src/components/mental-health/mental-wellbeing.tsx
index 454f333dc..8f40e14cf 100644
--- a/src/components/mental-health/mental-wellbeing.tsx
+++ b/src/components/mental-health/mental-wellbeing.tsx
@@ -26,6 +26,7 @@ import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useTranslations } from "@/lib/i18n/context";
 import { apiGet, apiPost } from "@/lib/api/api-fetch";
 import { queryKeys } from "@/lib/query-keys";
+import { PageHeader } from "@/components/ui/page-header";
 import { ResponsiveSheet } from "@/components/ui/responsive-sheet";
 
 import { AssessmentHistory } from "./assessment-history";
@@ -107,14 +108,12 @@ export function MentalWellbeing() {
     <div className="flex flex-col gap-6">
       {phase === "choose" && (
         <>
-          <header className="flex flex-col gap-2">
-            {/* Title kept for screen readers / document outline only — the
-                visible heading + its tooltip were removed (§ Marc v1.25.5). */}
-            <h1 className="sr-only">{t("mentalHealth.pageTitle")}</h1>
-            <p className="text-muted-foreground text-sm">
-              {t("mentalHealth.pageDescription")}
-            </p>
-          </header>
+          {/* v1.26 — visible page header, consistent with every other module
+              (the title was previously sr-only; the description stays). */}
+          <PageHeader
+            title={t("mentalHealth.pageTitle")}
+            description={t("mentalHealth.pageDescription")}
+          />
 
           <section aria-label={t("mentalHealth.choosePrompt")}>
             <h2 className="sr-only">{t("mentalHealth.choosePrompt")}</h2>
diff --git a/src/components/mood/mood-list.tsx b/src/components/mood/mood-list.tsx
index fc8f92199..9b0963845 100644
--- a/src/components/mood/mood-list.tsx
+++ b/src/components/mood/mood-list.tsx
@@ -5,6 +5,8 @@ import { useAuth } from "@/hooks/use-auth";
 import { Button } from "@/components/ui/button";
 import { Badge } from "@/components/ui/badge";
 import { EmptyState } from "@/components/ui/empty-state";
+import { QueryErrorCard } from "@/components/ui/query-error-card";
+import { Skeleton } from "@/components/ui/skeleton";
 import {
   FilterBar,
   FilterBarDateRange,
@@ -43,7 +45,6 @@ import {
   Loader2,
   Pencil,
   Plus,
-  RefreshCw,
   Smile,
   Trash2,
   ChevronLeft,
@@ -500,27 +501,18 @@ export function MoodList({ onAddFirst }: MoodListProps = {}) {
         </FilterBar>
 
         {isLoading ? (
-          <div className="flex h-32 items-center justify-center">
-            <Loader2 className="text-primary h-6 w-6 animate-spin motion-reduce:animate-none" />
+          <div className="space-y-2" data-slot="mood-list-loading">
+            {Array.from({ length: 6 }, (_, i) => (
+              <Skeleton key={i} className="h-14 w-full rounded-lg" />
+            ))}
           </div>
         ) : isError ? (
-          <div
-            role="alert"
-            data-slot="mood-list-error"
-            className="text-muted-foreground flex flex-col items-start gap-3 py-8 text-sm sm:flex-row sm:items-center sm:justify-between"
-          >
-            <span>{t("mood.loadError")}</span>
-            <Button
-              type="button"
-              size="sm"
-              variant="outline"
-              onClick={() => void refetch()}
-              className="gap-1.5"
-            >
-              <RefreshCw className="h-3.5 w-3.5" aria-hidden="true" />
-              <span>{t("common.retry")}</span>
-            </Button>
-          </div>
+          // A read failure is NOT an empty list — surface the error + Retry so
+          // an outage never reads as "you have no mood entries".
+          <QueryErrorCard
+            title={t("mood.loadError")}
+            onRetry={() => void refetch()}
+          />
         ) : !data?.entries?.length ? (
           // v1.4.15 phase-C5: replace bare-text empty rectangle with
           // EmptyState. Filter-aware copy splits "no mood entries yet"
diff --git a/src/components/ui/page-header.tsx b/src/components/ui/page-header.tsx
new file mode 100644
index 000000000..66469203e
--- /dev/null
+++ b/src/components/ui/page-header.tsx
@@ -0,0 +1,43 @@
+import type { ReactNode } from "react";
+
+import { BackLink } from "@/components/ui/back-link";
+import { cn } from "@/lib/utils";
+
+/**
+ * The one canonical page header. Every module surface renders its title
+ * through this so the header vocabulary reads identically app-wide: the H1
+ * is always `text-2xl font-bold tracking-tight`, the description is always
+ * `text-muted-foreground text-sm`, and no icon sits beside the H1. An
+ * optional back-link rides above the title, and an `actions` slot holds the
+ * page's primary buttons to the right of the title block.
+ */
+export function PageHeader({
+  title,
+  description,
+  backLink,
+  actions,
+  className,
+}: {
+  title: ReactNode;
+  description?: ReactNode;
+  backLink?: { href: string; label: string; dataSlot?: string };
+  actions?: ReactNode;
+  className?: string;
+}) {
+  return (
+    <div className={cn("space-y-1.5", className)}>
+      {backLink ? <BackLink {...backLink} /> : null}
+      <div className="flex items-start justify-between gap-3">
+        <div className="min-w-0 space-y-1.5">
+          <h1 className="text-2xl font-bold tracking-tight">{title}</h1>
+          {description ? (
+            <p className="text-muted-foreground text-sm">{description}</p>
+          ) : null}
+        </div>
+        {actions ? (
+          <div className="flex shrink-0 items-center gap-2">{actions}</div>
+        ) : null}
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/ui/query-error-card.tsx b/src/components/ui/query-error-card.tsx
new file mode 100644
index 000000000..98edbd8a3
--- /dev/null
+++ b/src/components/ui/query-error-card.tsx
@@ -0,0 +1,59 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { AlertTriangle, RotateCw } from "lucide-react";
+
+import { Button } from "@/components/ui/button";
+import { Card, CardContent } from "@/components/ui/card";
+import { useTranslations } from "@/lib/i18n/context";
+import { cn } from "@/lib/utils";
+
+/**
+ * Read-failure card for list / data surfaces.
+ *
+ * Mirrors `<ChartErrorState>`'s shape + tone (AlertTriangle, a title line, a
+ * muted description, an optional Retry button) but renders inside a `Card` so
+ * a list page can tell "load failed" apart from an honest empty state — a
+ * failed query must never fall through to the "no data yet" copy. Defaults are
+ * the generic `common.*` strings so a caller can drop it in with just
+ * `onRetry`; a surface with its own "couldn't load X" string passes it through
+ * `title` / `description`.
+ */
+export function QueryErrorCard({
+  title,
+  description,
+  onRetry,
+  retryLabel,
+  className,
+}: {
+  title?: ReactNode;
+  description?: ReactNode;
+  onRetry?: () => void;
+  retryLabel?: string;
+  className?: string;
+}) {
+  const { t } = useTranslations();
+  return (
+    <Card data-slot="query-error-card" className={cn(className)}>
+      <CardContent
+        role="alert"
+        className="flex flex-col items-center justify-center gap-3 px-6 py-10 text-center"
+      >
+        <AlertTriangle
+          className="text-muted-foreground/60 h-8 w-8"
+          aria-hidden="true"
+        />
+        <p className="text-sm font-medium">{title ?? t("common.loadFailed")}</p>
+        {description ? (
+          <p className="text-muted-foreground text-sm">{description}</p>
+        ) : null}
+        {onRetry ? (
+          <Button variant="outline" size="sm" onClick={onRetry}>
+            <RotateCw className="h-3.5 w-3.5" aria-hidden="true" />
+            {retryLabel ?? t("common.retry")}
+          </Button>
+        ) : null}
+      </CardContent>
+    </Card>
+  );
+}