diff --git a/ui/e2e/a11y.spec.ts b/ui/e2e/a11y.spec.ts
new file mode 100644
index 0000000..8c92381
--- /dev/null
+++ b/ui/e2e/a11y.spec.ts
@@ -0,0 +1,36 @@
+import { test, expect } from "./fixtures";
+import AxeBuilder from "@axe-core/playwright";
+
+const ROUTES = ["/", "/notes", "/docs", "/graph"];
+
+test.describe("axe a11y audit — zero violations", () => {
+  for (const url of ROUTES) {
+    test(`no violations on ${url}`, async ({ stubbedPage: page }) => {
+      await page.goto(url);
+      await page.locator("main#main").waitFor();
+      const results = await new AxeBuilder({ page })
+        .withTags(["wcag2a", "wcag2aa"])
+        .analyze();
+      expect(
+        results.violations,
+        `${url}:\n${JSON.stringify(results.violations, null, 2)}`,
+      ).toEqual([]);
+    });
+  }
+
+  test("no violations on /mcp (client-side nav)", async ({ stubbedPage: page }) => {
+    // /mcp is proxied in dev-server, navigate via SPA history.
+    await page.goto("/");
+    await page.locator("main#main").waitFor();
+    await page.evaluate(() => window.history.pushState({}, "", "/mcp"));
+    await page.evaluate(() => window.dispatchEvent(new PopStateEvent("popstate")));
+    await page.waitForTimeout(200);
+    const results = await new AxeBuilder({ page })
+      .withTags(["wcag2a", "wcag2aa"])
+      .analyze();
+    expect(
+      results.violations,
+      `/mcp:\n${JSON.stringify(results.violations, null, 2)}`,
+    ).toEqual([]);
+  });
+});
diff --git a/ui/e2e/focus.spec.ts b/ui/e2e/focus.spec.ts
new file mode 100644
index 0000000..4f9e747
--- /dev/null
+++ b/ui/e2e/focus.spec.ts
@@ -0,0 +1,44 @@
+import { test, expect } from "./fixtures";
+
+test.describe("focus management", () => {
+  test("skip-link is the first tab target and moves focus to main#main", async ({ stubbedPage: page }) => {
+    await page.goto("/");
+    await page.locator("main#main").waitFor();
+    await page.keyboard.press("Tab");
+    const focusedIsSkipLink = await page.evaluate(
+      () => document.activeElement?.textContent?.toLowerCase().includes("skip to main content") ?? false,
+    );
+    expect(focusedIsSkipLink).toBe(true);
+    await page.keyboard.press("Enter");
+    const mainFocused = await page.evaluate(() => document.activeElement?.id === "main");
+    expect(mainFocused).toBe(true);
+  });
+
+  test("command palette returns focus to the invoking button on close", async ({ stubbedPage: page }) => {
+    await page.goto("/");
+    await page.locator("main#main").waitFor();
+    const searchBtn = page.locator(".site-header-search").first();
+    await searchBtn.focus();
+    await expect(searchBtn).toBeFocused();
+    await page.keyboard.press("Enter");
+    await page.getByPlaceholder(/search notes, docs, entities/i).waitFor();
+    await page.keyboard.press("Escape");
+    // After close, focus must return to the search button.
+    await expect(searchBtn).toBeFocused();
+  });
+
+  test("dialog traps focus while open (radix)", async ({ stubbedPage: page }) => {
+    await page.goto("/");
+    await page.locator("main#main").waitFor();
+    await page.keyboard.press("ControlOrMeta+k");
+    await page.getByPlaceholder(/search notes, docs, entities/i).waitFor();
+    // Tab 20 times; focus must stay inside the palette dialog.
+    for (let i = 0; i < 20; i++) {
+      await page.keyboard.press("Tab");
+      const inside = await page.evaluate(() =>
+        Boolean(document.activeElement?.closest("[role=\"dialog\"]")),
+      );
+      expect(inside, `focus escaped the dialog on Tab ${i}`).toBe(true);
+    }
+  });
+});
diff --git a/ui/e2e/mobile.spec.ts b/ui/e2e/mobile.spec.ts
new file mode 100644
index 0000000..66fb5fc
--- /dev/null
+++ b/ui/e2e/mobile.spec.ts
@@ -0,0 +1,55 @@
+import { test as fixtureTest, expect } from "./fixtures";
+
+const mobileTest = fixtureTest.extend({});
+mobileTest.use({ viewport: { width: 375, height: 812 } });
+
+mobileTest.describe("mobile 375px viewport", () => {
+  mobileTest("sidebar collapses at 375px", async ({ stubbedPage: page }) => {
+    await page.goto("/");
+    await page.locator("main#main").waitFor();
+    // The shadcn sidebar hides on mobile by default; assert it is not part of
+    // the initial visible tab-order.
+    const collapsedOrHidden = await page.evaluate(() => {
+      const sb = document.querySelector("[data-slot='sidebar'], [data-sidebar='sidebar']");
+      if (!sb) return true; // treated as collapsed if not rendered
+      const r = sb.getBoundingClientRect();
+      return r.width < 60 || r.left < -10 || getComputedStyle(sb).display === "none";
+    });
+    expect(collapsedOrHidden).toBe(true);
+  });
+
+  mobileTest("header buttons meet 44x44 tap-target minimum", async ({ stubbedPage: page }) => {
+    await page.goto("/");
+    await page.locator("main#main").waitFor();
+    const buttons = page.locator(".site-header button, .site-header a[role='button']");
+    const count = await buttons.count();
+    for (let i = 0; i < count; i++) {
+      const box = await buttons.nth(i).boundingBox();
+      if (!box) continue; // button hidden on this viewport
+      expect.soft(box.width, `button ${i} too narrow`).toBeGreaterThanOrEqual(44);
+      expect.soft(box.height, `button ${i} too short`).toBeGreaterThanOrEqual(44);
+    }
+  });
+
+  mobileTest("command palette fills the viewport", async ({ stubbedPage: page }) => {
+    await page.goto("/");
+    await page.locator("main#main").waitFor();
+    await page.keyboard.press("ControlOrMeta+k");
+    const dialog = page.locator("[role='dialog']").first();
+    await dialog.waitFor();
+    const box = await dialog.boundingBox();
+    expect(box?.width ?? 0).toBeGreaterThanOrEqual(320);
+  });
+
+  mobileTest("documents list does not overflow horizontally", async ({ stubbedPage: page }) => {
+    await page.goto("/docs");
+    await page.locator("main#main").waitFor();
+    // Detect horizontal scroll on <body> — tables should scroll inside their
+    // wrapper, not push the body.
+    const bodyOverflow = await page.evaluate(() => {
+      const d = document.documentElement;
+      return d.scrollWidth - d.clientWidth;
+    });
+    expect(bodyOverflow).toBeLessThanOrEqual(1);
+  });
+});
diff --git a/ui/e2e/no-console-errors.spec.ts b/ui/e2e/no-console-errors.spec.ts
new file mode 100644
index 0000000..d5b2016
--- /dev/null
+++ b/ui/e2e/no-console-errors.spec.ts
@@ -0,0 +1,57 @@
+import { test, expect } from "./fixtures";
+
+// All Block 5 primary routes. `/mcp` is navigated via client-side routing
+// from `/` because the Vite dev-server has a proxy rule for `/mcp` that
+// would otherwise intercept the document request.
+const ROUTES = ["/", "/notes", "/docs", "/graph"];
+
+test.describe("no update-depth warnings on any route", () => {
+  for (const url of ROUTES) {
+    test(`no update-depth warning on ${url}`, async ({ stubbedPage: page }) => {
+      const errors: string[] = [];
+      const warnings: string[] = [];
+      page.on("console", (msg) => {
+        const text = msg.text();
+        if (msg.type() === "error") errors.push(text);
+        if (msg.type() === "warning") warnings.push(text);
+      });
+      page.on("pageerror", (err) => errors.push(err.message));
+
+      await page.goto(url);
+      await page.locator("main#main").waitFor();
+      // Give effects a tick to run — if there's an infinite loop, it fires
+      // within a few microtasks and the warning lands here.
+      await page.waitForTimeout(500);
+
+      const offending = [...errors, ...warnings].filter((t) =>
+        /maximum update depth|too many re-renders/i.test(t),
+      );
+      expect(offending, `${url} emitted: ${offending.join(" | ")}`).toEqual([]);
+    });
+  }
+
+  test("no update-depth warning on /mcp (client-side nav)", async ({ stubbedPage: page }) => {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+    page.on("console", (msg) => {
+      const text = msg.text();
+      if (msg.type() === "error") errors.push(text);
+      if (msg.type() === "warning") warnings.push(text);
+    });
+    page.on("pageerror", (err) => errors.push(err.message));
+
+    // Start at Home, then navigate to /mcp via SPA history — this avoids the
+    // Vite dev-server /mcp proxy rule that otherwise serves a 404 from the
+    // backend port when a document request is issued directly.
+    await page.goto("/");
+    await page.locator("main#main").waitFor();
+    await page.evaluate(() => window.history.pushState({}, "", "/mcp"));
+    await page.evaluate(() => window.dispatchEvent(new PopStateEvent("popstate")));
+    await page.waitForTimeout(500);
+
+    const offending = [...errors, ...warnings].filter((t) =>
+      /maximum update depth|too many re-renders/i.test(t),
+    );
+    expect(offending, `/mcp emitted: ${offending.join(" | ")}`).toEqual([]);
+  });
+});
diff --git a/ui/e2e/safe-area.spec.ts b/ui/e2e/safe-area.spec.ts
new file mode 100644
index 0000000..98e2cc7
--- /dev/null
+++ b/ui/e2e/safe-area.spec.ts
@@ -0,0 +1,24 @@
+import { test as fixtureTest, expect } from "./fixtures";
+
+// Simulate an iPhone 14 viewport on the configured Chromium project rather
+// than using devices["iPhone 14"] (which pins the webkit engine). The
+// browser engine is not what this test exercises — the CSS rule is. The
+// 390x844 dimensions match the iPhone 14 logical viewport.
+fixtureTest.use({
+  viewport: { width: 390, height: 844 },
+  deviceScaleFactor: 3,
+  isMobile: true,
+  hasTouch: true,
+});
+
+fixtureTest("header padding accommodates safe-area-inset-top on iPhone 14 viewport", async ({ stubbedPage: page }) => {
+  await page.goto("/");
+  await page.locator("main#main").waitFor();
+  const header = page.locator(".site-header").first();
+  await expect(header).toBeVisible();
+  const paddingTopPx = await header.evaluate(
+    (el) => parseFloat(getComputedStyle(el).paddingTop),
+  );
+  // max(1rem, env(safe-area-inset-top)) must be at least 1rem = 16px.
+  expect(paddingTopPx).toBeGreaterThanOrEqual(16);
+});
diff --git a/ui/e2e/theme-flash.spec.ts b/ui/e2e/theme-flash.spec.ts
new file mode 100644
index 0000000..6eb1ebe
--- /dev/null
+++ b/ui/e2e/theme-flash.spec.ts
@@ -0,0 +1,55 @@
+import { test, expect } from "./fixtures";
+
+test.describe("theme-flash", () => {
+  test("dark theme is applied before React hydrates", async ({ stubbedPage: page }) => {
+    // Seed localStorage BEFORE navigating so the inline script can read it.
+    await page.addInitScript(() => {
+      window.localStorage.setItem(
+        "docsiq-ui",
+        JSON.stringify({ state: { theme: "dark" }, version: 0 }),
+      );
+    });
+    await page.goto("/");
+    // Check the html element's class list at the earliest opportunity.
+    const hasDark = await page.evaluate(() =>
+      document.documentElement.classList.contains("dark"),
+    );
+    expect(hasDark).toBe(true);
+    // And data-theme is set too
+    const themeAttr = await page.evaluate(() =>
+      document.documentElement.dataset.theme,
+    );
+    expect(themeAttr).toBe("dark");
+  });
+
+  test("light theme renders without .dark class", async ({ stubbedPage: page }) => {
+    await page.addInitScript(() => {
+      window.localStorage.setItem(
+        "docsiq-ui",
+        JSON.stringify({ state: { theme: "light" }, version: 0 }),
+      );
+    });
+    await page.goto("/");
+    const hasDark = await page.evaluate(() =>
+      document.documentElement.classList.contains("dark"),
+    );
+    expect(hasDark).toBe(false);
+  });
+
+  test("system theme resolves via prefers-color-scheme before hydration", async ({ browser }) => {
+    const ctx = await browser.newContext({ colorScheme: "dark" });
+    const p2 = await ctx.newPage();
+    await p2.addInitScript(() => {
+      window.localStorage.setItem(
+        "docsiq-ui",
+        JSON.stringify({ state: { theme: "system" }, version: 0 }),
+      );
+    });
+    await p2.goto("/");
+    const hasDark = await p2.evaluate(() =>
+      document.documentElement.classList.contains("dark"),
+    );
+    expect(hasDark).toBe(true);
+    await ctx.close();
+  });
+});
diff --git a/ui/index.html b/ui/index.html
index e7c5e5b..158abc8 100644
--- a/ui/index.html
+++ b/ui/index.html
@@ -11,6 +11,37 @@
     <link rel="apple-touch-icon" href="/favicon.svg" />
     <link rel="manifest" href="/manifest.webmanifest" />
     <title>docsiq — GraphRAG knowledge base</title>
+    <script>
+      // Block 5.9 — theme-flash guard. Applies the persisted theme class
+      // before React hydrates so there is no FOUC on first paint. Must run
+      // synchronously in <head>. Keep in sync with Zustand persist key
+      // `docsiq-ui` and the Providers.tsx effect that toggles .dark.
+      (function () {
+        try {
+          var raw = localStorage.getItem("docsiq-ui");
+          var theme = "system";
+          if (raw) {
+            var parsed = JSON.parse(raw);
+            if (parsed && parsed.state && typeof parsed.state.theme === "string") {
+              theme = parsed.state.theme;
+            }
+          }
+          var effective = theme;
+          if (theme === "system") {
+            effective = window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches
+              ? "dark"
+              : "light";
+          }
+          var root = document.documentElement;
+          root.dataset.theme = effective;
+          if (effective === "dark") root.classList.add("dark");
+        } catch (e) {
+          // If localStorage is unavailable (privacy mode) we simply let
+          // React decide after hydration; there is a brief FOUC but no
+          // crash. Do not log — this runs before any logger is attached.
+        }
+      })();
+    </script>
   </head>
   <body>
     <div id="root"></div>
diff --git a/ui/package-lock.json b/ui/package-lock.json
index 9f3faa9..ad94651 100644
--- a/ui/package-lock.json
+++ b/ui/package-lock.json
@@ -55,6 +55,7 @@
         "zustand": "^5.0.2"
       },
       "devDependencies": {
+        "@axe-core/playwright": "^4.11.2",
         "@playwright/test": "^1.59.1",
         "@tailwindcss/vite": "^4.0.0",
         "@testing-library/jest-dom": "^6.9.1",
@@ -100,6 +101,19 @@
         "lru-cache": "^10.4.3"
       }
     },
+    "node_modules/@axe-core/playwright": {
+      "version": "4.11.2",
+      "resolved": "https://registry.npmjs.org/@axe-core/playwright/-/playwright-4.11.2.tgz",
+      "integrity": "sha512-iP6hfNl9G0j/SEUSo8M7D80RbcDo9KRAAfDP4IT5OHB+Wm6zUHIrm8Y51BKI+Oyqduvipf9u1hcRy57zCBKzWQ==",
+      "dev": true,
+      "license": "MPL-2.0",
+      "dependencies": {
+        "axe-core": "~4.11.3"
+      },
+      "peerDependencies": {
+        "playwright-core": ">= 1.0.0"
+      }
+    },
     "node_modules/@babel/code-frame": {
       "version": "7.29.0",
       "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.29.0.tgz",
diff --git a/ui/package.json b/ui/package.json
index 994d721..49f8763 100644
--- a/ui/package.json
+++ b/ui/package.json
@@ -64,6 +64,7 @@
     "zustand": "^5.0.2"
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.11.2",
     "@playwright/test": "^1.59.1",
     "@tailwindcss/vite": "^4.0.0",
     "@testing-library/jest-dom": "^6.9.1",
diff --git a/ui/src/App.tsx b/ui/src/App.tsx
index 84b7aa0..44d5331 100644
--- a/ui/src/App.tsx
+++ b/ui/src/App.tsx
@@ -2,6 +2,8 @@ import { lazy, Suspense, useEffect } from "react";
 import { Route, Routes } from "react-router-dom";
 import { Providers } from "@/components/layout/Providers";
 import { Shell } from "@/components/layout/Shell";
+import { RouteBoundary } from "@/components/layout/RouteBoundary";
+import { LoadingSkeleton } from "@/components/empty";
 import { initAuth } from "@/lib/api-client";
 import Home from "@/routes/Home";
 
@@ -16,7 +18,11 @@ const Graph = lazy(() => import("@/routes/Graph"));
 const MCPConsole = lazy(() => import("@/routes/MCPConsole"));
 
 function RouteFallback() {
-  return <div className="p-6 text-sm text-muted-foreground">loading…</div>;
+  return (
+    <div className="p-6">
+      <LoadingSkeleton label="Loading view" rows={4} />
+    </div>
+  );
 }
 
 export default function App() {
@@ -24,21 +30,23 @@ export default function App() {
   return (
     <Providers>
       <Shell>
-        <Suspense fallback={<RouteFallback />}>
-          <Routes>
-            <Route path="/" element={<Home />} />
-            <Route path="/notes" element={<NotesLayout />}>
-              <Route path="search" element={<NotesSearch />} />
-              <Route path=":key" element={<NoteView />} />
-              <Route path=":key/edit" element={<NoteEditor />} />
-            </Route>
-            <Route path="/docs" element={<DocumentsList />} />
-            <Route path="/docs/:id" element={<DocumentView />} />
-            <Route path="/graph" element={<Graph />} />
-            <Route path="/mcp" element={<MCPConsole />} />
-            <Route path="*" element={<NotFound />} />
-          </Routes>
-        </Suspense>
+        <RouteBoundary>
+          <Suspense fallback={<RouteFallback />}>
+            <Routes>
+              <Route path="/" element={<Home />} />
+              <Route path="/notes" element={<NotesLayout />}>
+                <Route path="search" element={<NotesSearch />} />
+                <Route path=":key" element={<NoteView />} />
+                <Route path=":key/edit" element={<NoteEditor />} />
+              </Route>
+              <Route path="/docs" element={<DocumentsList />} />
+              <Route path="/docs/:id" element={<DocumentView />} />
+              <Route path="/graph" element={<Graph />} />
+              <Route path="/mcp" element={<MCPConsole />} />
+              <Route path="*" element={<NotFound />} />
+            </Routes>
+          </Suspense>
+        </RouteBoundary>
       </Shell>
     </Providers>
   );
diff --git a/ui/src/components/app-sidebar.tsx b/ui/src/components/app-sidebar.tsx
index 4cfdd30..11ec573 100644
--- a/ui/src/components/app-sidebar.tsx
+++ b/ui/src/components/app-sidebar.tsx
@@ -85,7 +85,7 @@ export function AppSidebar(props: React.ComponentProps<typeof Sidebar>) {
             Project
           </label>
           <Select value={slug} onValueChange={setSlug}>
-            <SelectTrigger className="w-full h-8 text-xs font-mono">
+            <SelectTrigger aria-label="Select project" className="w-full h-8 text-xs font-mono">
               <SelectValue />
             </SelectTrigger>
             <SelectContent>
diff --git a/ui/src/components/empty/EmptyState.tsx b/ui/src/components/empty/EmptyState.tsx
new file mode 100644
index 0000000..196d3b4
--- /dev/null
+++ b/ui/src/components/empty/EmptyState.tsx
@@ -0,0 +1,27 @@
+import type { ReactNode } from "react";
+import { Inbox } from "lucide-react";
+
+interface EmptyStateProps {
+  title: string;
+  description: string;
+  icon?: ReactNode;
+  action?: ReactNode;
+}
+
+export function EmptyState({ title, description, icon, action }: EmptyStateProps) {
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className="state-card state-card--empty"
+      data-testid="empty-state"
+    >
+      <div className="state-card__icon" aria-hidden="true">
+        {icon ?? <Inbox className="size-6" />}
+      </div>
+      <h3 className="state-card__title">{title}</h3>
+      <p className="state-card__description">{description}</p>
+      {action ? <div className="state-card__action">{action}</div> : null}
+    </div>
+  );
+}
diff --git a/ui/src/components/empty/ErrorState.tsx b/ui/src/components/empty/ErrorState.tsx
new file mode 100644
index 0000000..301a74b
--- /dev/null
+++ b/ui/src/components/empty/ErrorState.tsx
@@ -0,0 +1,41 @@
+import { AlertTriangle } from "lucide-react";
+import { Button } from "@/components/ui/button";
+
+interface ErrorStateProps {
+  title: string;
+  message: string;
+  onRetry?: () => void;
+}
+
+const MAX_MESSAGE_LEN = 500;
+
+function sanitize(raw: string): string {
+  const trimmed = raw.trim().replace(/\s+/g, " ");
+  if (trimmed.length <= MAX_MESSAGE_LEN) return trimmed;
+  return `${trimmed.slice(0, MAX_MESSAGE_LEN)}…`;
+}
+
+export function ErrorState({ title, message, onRetry }: ErrorStateProps) {
+  return (
+    <div
+      role="alert"
+      className="state-card state-card--error"
+      data-testid="error-state"
+    >
+      <div className="state-card__icon state-card__icon--danger" aria-hidden="true">
+        <AlertTriangle className="size-6" />
+      </div>
+      <h3 className="state-card__title">{title}</h3>
+      <p className="state-card__description" data-testid="error-message">
+        {sanitize(message)}
+      </p>
+      {onRetry ? (
+        <div className="state-card__action">
+          <Button type="button" size="sm" variant="outline" onClick={onRetry}>
+            Retry
+          </Button>
+        </div>
+      ) : null}
+    </div>
+  );
+}
diff --git a/ui/src/components/empty/LoadingSkeleton.tsx b/ui/src/components/empty/LoadingSkeleton.tsx
new file mode 100644
index 0000000..0ee77cd
--- /dev/null
+++ b/ui/src/components/empty/LoadingSkeleton.tsx
@@ -0,0 +1,26 @@
+import { Skeleton } from "@/components/ui/skeleton";
+
+interface LoadingSkeletonProps {
+  label: string;
+  rows?: number;
+}
+
+export function LoadingSkeleton({ label, rows = 3 }: LoadingSkeletonProps) {
+  const count = Math.max(1, rows);
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      aria-label={label}
+      className="state-card state-card--loading"
+      data-testid="loading-skeleton"
+    >
+      <div className="state-card__bars">
+        {Array.from({ length: count }).map((_, i) => (
+          <Skeleton key={i} data-testid="skeleton-row" className="state-card__bar" />
+        ))}
+      </div>
+      <span className="sr-only">{label}</span>
+    </div>
+  );
+}
diff --git a/ui/src/components/empty/__tests__/EmptyState.test.tsx b/ui/src/components/empty/__tests__/EmptyState.test.tsx
new file mode 100644
index 0000000..af04d2f
--- /dev/null
+++ b/ui/src/components/empty/__tests__/EmptyState.test.tsx
@@ -0,0 +1,28 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { EmptyState } from "../EmptyState";
+
+describe("EmptyState", () => {
+  it("renders title and description", () => {
+    render(<EmptyState title="No notes yet" description="Create one to get started." />);
+    expect(screen.getByRole("status")).toBeInTheDocument();
+    expect(screen.getByText("No notes yet")).toBeInTheDocument();
+    expect(screen.getByText("Create one to get started.")).toBeInTheDocument();
+  });
+
+  it("renders an action slot when provided", () => {
+    render(
+      <EmptyState
+        title="No notes"
+        description="Try ingesting one."
+        action={<button type="button">Ingest</button>}
+      />,
+    );
+    expect(screen.getByRole("button", { name: /ingest/i })).toBeInTheDocument();
+  });
+
+  it("exposes role=status so screen readers announce it", () => {
+    render(<EmptyState title="x" description="y" />);
+    expect(screen.getByRole("status")).toHaveAttribute("aria-live", "polite");
+  });
+});
diff --git a/ui/src/components/empty/__tests__/ErrorState.test.tsx b/ui/src/components/empty/__tests__/ErrorState.test.tsx
new file mode 100644
index 0000000..0db95bb
--- /dev/null
+++ b/ui/src/components/empty/__tests__/ErrorState.test.tsx
@@ -0,0 +1,30 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi } from "vitest";
+import { ErrorState } from "../ErrorState";
+
+describe("ErrorState", () => {
+  it("renders the message and a retry button when retry is provided", async () => {
+    const retry = vi.fn();
+    render(
+      <ErrorState title="Failed to load" message="Network error" onRetry={retry} />,
+    );
+    expect(screen.getByRole("alert")).toBeInTheDocument();
+    expect(screen.getByText("Failed to load")).toBeInTheDocument();
+    expect(screen.getByText("Network error")).toBeInTheDocument();
+    await userEvent.click(screen.getByRole("button", { name: /retry/i }));
+    expect(retry).toHaveBeenCalledOnce();
+  });
+
+  it("hides the retry button when onRetry is absent", () => {
+    render(<ErrorState title="Broken" message="x" />);
+    expect(screen.queryByRole("button", { name: /retry/i })).toBeNull();
+  });
+
+  it("sanitizes long messages to 500 chars", () => {
+    const long = "a".repeat(900);
+    render(<ErrorState title="t" message={long} />);
+    const rendered = screen.getByTestId("error-message").textContent ?? "";
+    expect(rendered.length).toBeLessThanOrEqual(504); // 500 + ellipsis
+  });
+});
diff --git a/ui/src/components/empty/__tests__/LoadingSkeleton.test.tsx b/ui/src/components/empty/__tests__/LoadingSkeleton.test.tsx
new file mode 100644
index 0000000..a465b7c
--- /dev/null
+++ b/ui/src/components/empty/__tests__/LoadingSkeleton.test.tsx
@@ -0,0 +1,22 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { LoadingSkeleton } from "../LoadingSkeleton";
+
+describe("LoadingSkeleton", () => {
+  it("renders a polite live-region with a label", () => {
+    render(<LoadingSkeleton label="Loading notes" />);
+    const status = screen.getByRole("status");
+    expect(status).toHaveAttribute("aria-live", "polite");
+    expect(status).toHaveAttribute("aria-label", "Loading notes");
+  });
+
+  it("renders `rows` skeleton bars", () => {
+    render(<LoadingSkeleton label="Loading" rows={4} />);
+    expect(screen.getAllByTestId("skeleton-row")).toHaveLength(4);
+  });
+
+  it("defaults to 3 rows when no count given", () => {
+    render(<LoadingSkeleton label="Loading" />);
+    expect(screen.getAllByTestId("skeleton-row")).toHaveLength(3);
+  });
+});
diff --git a/ui/src/components/empty/index.ts b/ui/src/components/empty/index.ts
new file mode 100644
index 0000000..ff06481
--- /dev/null
+++ b/ui/src/components/empty/index.ts
@@ -0,0 +1,3 @@
+export { EmptyState } from "./EmptyState";
+export { LoadingSkeleton } from "./LoadingSkeleton";
+export { ErrorState } from "./ErrorState";
diff --git a/ui/src/components/layout/RouteBoundary.tsx b/ui/src/components/layout/RouteBoundary.tsx
new file mode 100644
index 0000000..fdb31ec
--- /dev/null
+++ b/ui/src/components/layout/RouteBoundary.tsx
@@ -0,0 +1,78 @@
+import { Component, type ErrorInfo, type ReactNode } from "react";
+import { AlertTriangle } from "lucide-react";
+import { Button } from "@/components/ui/button";
+
+interface RouteBoundaryProps { children: ReactNode }
+interface RouteBoundaryState { error: Error | null }
+
+const MAX_MESSAGE_LEN = 500;
+const REPORT_EMAIL = "docsiq-support@example.invalid";
+
+function sanitize(raw: string): string {
+  const trimmed = raw.trim().replace(/\s+/g, " ");
+  if (trimmed.length <= MAX_MESSAGE_LEN) return trimmed;
+  return `${trimmed.slice(0, MAX_MESSAGE_LEN)}…`;
+}
+
+function buildMailto(err: Error): string {
+  const subject = encodeURIComponent(`[docsiq] Render error: ${err.name}`);
+  const bodyLines = [
+    "What I was doing:",
+    "",
+    "",
+    "Message:",
+    sanitize(err.message),
+    "",
+    "Stack (truncated):",
+    (err.stack ?? "").split("\n").slice(0, 10).join("\n"),
+    "",
+    `URL: ${typeof window !== "undefined" ? window.location.href : ""}`,
+    `UA:  ${typeof navigator !== "undefined" ? navigator.userAgent : ""}`,
+  ].join("\n");
+  const body = encodeURIComponent(bodyLines);
+  return `mailto:${REPORT_EMAIL}?subject=${subject}&body=${body}`;
+}
+
+export class RouteBoundary extends Component<RouteBoundaryProps, RouteBoundaryState> {
+  state: RouteBoundaryState = { error: null };
+
+  static getDerivedStateFromError(error: Error): RouteBoundaryState {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    // slog-equivalent: keep one structured line; never dump user PII
+    // eslint-disable-next-line no-console
+    console.error("[RouteBoundary]", error.name, sanitize(error.message), info.componentStack);
+  }
+
+  private reset = () => this.setState({ error: null });
+
+  render() {
+    const { error } = this.state;
+    if (!error) return this.props.children;
+    return (
+      <div role="alert" className="state-card state-card--error" data-testid="route-boundary">
+        <div className="state-card__icon state-card__icon--danger" aria-hidden="true">
+          <AlertTriangle className="size-6" />
+        </div>
+        <h3 className="state-card__title">Something went wrong</h3>
+        <p className="state-card__description" data-testid="boundary-message">
+          {sanitize(error.message || "Unknown render error")}
+        </p>
+        <div className="state-card__action flex gap-2">
+          <Button type="button" size="sm" variant="outline" onClick={this.reset}>
+            Reload this view
+          </Button>
+          <a
+            className="inline-flex items-center justify-center rounded-md border px-3 py-1.5 text-sm hover:bg-accent"
+            href={buildMailto(error)}
+            rel="noopener noreferrer"
+          >
+            Report
+          </a>
+        </div>
+      </div>
+    );
+  }
+}
diff --git a/ui/src/components/layout/Shell.tsx b/ui/src/components/layout/Shell.tsx
index c6c03ad..2c1a75c 100644
--- a/ui/src/components/layout/Shell.tsx
+++ b/ui/src/components/layout/Shell.tsx
@@ -1,4 +1,4 @@
-import { type ReactNode, useState } from "react";
+import { type ReactNode, useCallback, useRef, useState } from "react";
 import { useNavigate } from "react-router-dom";
 import { AppSidebar } from "@/components/app-sidebar";
 import { SiteHeader } from "@/components/site-header";
@@ -10,10 +10,31 @@ import { CommandPalette } from "@/components/command/CommandPalette";
 
 export function Shell({ children }: { children: ReactNode }) {
   const [cmdOpen, setCmdOpen] = useState(false);
+  const invokerRef = useRef<HTMLElement | null>(null);
   const navigate = useNavigate();
   useDocumentTitle();
 
-  useHotkey("mod+k", () => setCmdOpen((v) => !v));
+  const openPalette = useCallback(() => {
+    const el = document.activeElement;
+    invokerRef.current = el instanceof HTMLElement ? el : null;
+    setCmdOpen(true);
+  }, []);
+
+  const handleOpenChange = useCallback((next: boolean) => {
+    setCmdOpen(next);
+    if (!next) {
+      // Wait one tick so Radix finishes its unmount animation before we
+      // restore focus, or the browser may re-steal it.
+      requestAnimationFrame(() => {
+        const target = invokerRef.current;
+        if (target && typeof target.focus === "function") {
+          target.focus();
+        }
+      });
+    }
+  }, []);
+
+  useHotkey("mod+k", () => (cmdOpen ? setCmdOpen(false) : openPalette()));
   useHotkey("g,h", () => navigate("/"));
   useHotkey("g,n", () => navigate("/notes"));
   useHotkey("g,d", () => navigate("/docs"));
@@ -32,7 +53,7 @@ export function Shell({ children }: { children: ReactNode }) {
       <SkipLink />
       <AppSidebar variant="inset" />
       <SidebarInset>
-        <SiteHeader onCommandOpen={() => setCmdOpen(true)} />
+        <SiteHeader onCommandOpen={openPalette} />
         <main
           id="main"
           role="main"
@@ -42,7 +63,7 @@ export function Shell({ children }: { children: ReactNode }) {
           {children}
         </main>
       </SidebarInset>
-      <CommandPalette open={cmdOpen} onOpenChange={setCmdOpen} />
+      <CommandPalette open={cmdOpen} onOpenChange={handleOpenChange} />
     </SidebarProvider>
   );
 }
diff --git a/ui/src/components/layout/__tests__/RouteBoundary.test.tsx b/ui/src/components/layout/__tests__/RouteBoundary.test.tsx
new file mode 100644
index 0000000..91cbb49
--- /dev/null
+++ b/ui/src/components/layout/__tests__/RouteBoundary.test.tsx
@@ -0,0 +1,74 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import type { JSX } from "react";
+import { RouteBoundary } from "../RouteBoundary";
+
+function Boom({ fuse }: { fuse: boolean }): JSX.Element {
+  if (fuse) throw new Error("kaboom");
+  return <div>ok</div>;
+}
+
+describe("RouteBoundary", () => {
+  beforeEach(() => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("renders children when they do not throw", () => {
+    render(
+      <RouteBoundary>
+        <Boom fuse={false} />
+      </RouteBoundary>,
+    );
+    expect(screen.getByText("ok")).toBeInTheDocument();
+  });
+
+  it("catches render errors and shows the fallback card with sanitized message", () => {
+    render(
+      <RouteBoundary>
+        <Boom fuse />
+      </RouteBoundary>,
+    );
+    expect(screen.getByRole("alert")).toBeInTheDocument();
+    expect(screen.getByText(/something went wrong/i)).toBeInTheDocument();
+    expect(screen.getByText("kaboom")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /reload this view/i })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: /report/i })).toHaveAttribute(
+      "href",
+      expect.stringMatching(/^mailto:/),
+    );
+  });
+
+  it("resets on `Reload this view` click", async () => {
+    function Toggle() {
+      return <Boom fuse />;
+    }
+    render(
+      <RouteBoundary>
+        <Toggle />
+      </RouteBoundary>,
+    );
+    expect(screen.getByRole("alert")).toBeInTheDocument();
+    await userEvent.click(screen.getByRole("button", { name: /reload this view/i }));
+    // After reset the child still throws, but the reset did fire and the
+    // boundary re-caught. We simply assert the reload button is still
+    // reachable — which proves the reset handler ran without crashing.
+    expect(screen.getByRole("button", { name: /reload this view/i })).toBeInTheDocument();
+  });
+
+  it("truncates very long error messages", () => {
+    function LongBoom(): JSX.Element {
+      throw new Error("x".repeat(900));
+    }
+    render(
+      <RouteBoundary>
+        <LongBoom />
+      </RouteBoundary>,
+    );
+    const msg = screen.getByTestId("boundary-message").textContent ?? "";
+    expect(msg.length).toBeLessThanOrEqual(504);
+  });
+});
diff --git a/ui/src/hooks/__tests__/useDocumentTitle.test.tsx b/ui/src/hooks/__tests__/useDocumentTitle.test.tsx
new file mode 100644
index 0000000..1e0e123
--- /dev/null
+++ b/ui/src/hooks/__tests__/useDocumentTitle.test.tsx
@@ -0,0 +1,86 @@
+import { renderHook } from "@testing-library/react";
+import { MemoryRouter, Route, Routes } from "react-router-dom";
+import { describe, it, expect, afterEach } from "vitest";
+import { useDocumentTitle } from "../useDocumentTitle";
+
+function Wrapper({
+  path,
+  url,
+  parts,
+}: {
+  path: string;
+  url: string;
+  parts?: string[];
+}) {
+  function Inner() {
+    useDocumentTitle(parts);
+    return null;
+  }
+  return (
+    <MemoryRouter initialEntries={[url]}>
+      <Routes>
+        <Route path={path} element={<Inner />} />
+      </Routes>
+    </MemoryRouter>
+  );
+}
+
+describe("useDocumentTitle", () => {
+  afterEach(() => {
+    document.title = "docsiq";
+  });
+
+  it("sets Home title", () => {
+    renderHook(() => {}, { wrapper: () => <Wrapper path="/" url="/" /> });
+    expect(document.title).toBe("Home — docsiq");
+  });
+
+  it("sets Notes list title", () => {
+    renderHook(() => {}, { wrapper: () => <Wrapper path="/notes" url="/notes" /> });
+    expect(document.title).toBe("Notes — docsiq");
+  });
+
+  it("sets note-key title from the URL when no parts passed", () => {
+    renderHook(() => {}, {
+      wrapper: () => (
+        <Wrapper path="/notes/:key" url="/notes/folder%2Fhello" />
+      ),
+    });
+    expect(document.title).toBe("hello — docsiq");
+  });
+
+  it("sets Documents list title", () => {
+    renderHook(() => {}, { wrapper: () => <Wrapper path="/docs" url="/docs" /> });
+    expect(document.title).toBe("Documents — docsiq");
+  });
+
+  it("honours caller-provided parts for a document view", () => {
+    renderHook(() => {}, {
+      wrapper: () => (
+        <Wrapper
+          path="/docs/:id"
+          url="/docs/abc"
+          parts={["Design doc v2", "Documents"]}
+        />
+      ),
+    });
+    expect(document.title).toBe("Design doc v2 — Documents — docsiq");
+  });
+
+  it("sets Graph title", () => {
+    renderHook(() => {}, { wrapper: () => <Wrapper path="/graph" url="/graph" /> });
+    expect(document.title).toBe("Graph — docsiq");
+  });
+
+  it("sets MCP Console title", () => {
+    renderHook(() => {}, { wrapper: () => <Wrapper path="/mcp" url="/mcp" /> });
+    expect(document.title).toBe("MCP Console — docsiq");
+  });
+
+  it("falls back to `docsiq` on unknown paths with no parts", () => {
+    renderHook(() => {}, {
+      wrapper: () => <Wrapper path="/weird" url="/weird" />,
+    });
+    expect(document.title).toBe("docsiq");
+  });
+});
diff --git a/ui/src/hooks/__tests__/useLastVisit.test.ts b/ui/src/hooks/__tests__/useLastVisit.test.ts
new file mode 100644
index 0000000..ca782e5
--- /dev/null
+++ b/ui/src/hooks/__tests__/useLastVisit.test.ts
@@ -0,0 +1,27 @@
+import { renderHook } from "@testing-library/react";
+import { describe, it, expect, beforeEach } from "vitest";
+import { useLastVisit } from "../useLastVisit";
+
+describe("useLastVisit reference stability (Block 5.5 regression)", () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  it("returns a stable `touch` function across renders", () => {
+    const { result, rerender } = renderHook(() => useLastVisit());
+    const first = result.current.touch;
+    rerender();
+    rerender();
+    rerender();
+    expect(result.current.touch).toBe(first);
+  });
+
+  it("touch() updates lastVisit but keeps `touch` identity stable", () => {
+    const { result, rerender } = renderHook(() => useLastVisit());
+    const firstTouch = result.current.touch;
+    result.current.touch();
+    rerender();
+    expect(result.current.touch).toBe(firstTouch);
+    expect(result.current.lastVisit).toBeGreaterThan(0);
+  });
+});
diff --git a/ui/src/hooks/useDocumentTitle.ts b/ui/src/hooks/useDocumentTitle.ts
index d38e51b..d926ab2 100644
--- a/ui/src/hooks/useDocumentTitle.ts
+++ b/ui/src/hooks/useDocumentTitle.ts
@@ -1,7 +1,7 @@
 import { useEffect } from "react";
 import { useLocation, useParams } from "react-router-dom";
 
-const TITLES: Record<string, string> = {
+const STATIC_TITLES: Record<string, string> = {
   "/": "Home",
   "/notes": "Notes",
   "/notes/search": "Search notes",
@@ -10,28 +10,50 @@ const TITLES: Record<string, string> = {
   "/mcp": "MCP Console",
 };
 
+const SUFFIX = "docsiq";
+
 function prettifyKey(raw: string): string {
   try {
-    return decodeURIComponent(raw).split("/").pop() || raw;
+    const decoded = decodeURIComponent(raw);
+    const last = decoded.split("/").pop();
+    return last && last.length > 0 ? last : decoded;
   } catch {
     return raw;
   }
 }
 
-export function useDocumentTitle() {
+/**
+ * Sets document.title with a consistent " — docsiq" suffix.
+ *
+ * `parts` takes precedence over path-derived titles. Pass a list of parts
+ * from most-specific to least-specific, e.g. ["Design doc v2", "Documents"]
+ * produces "Design doc v2 — Documents — docsiq".
+ */
+export function useDocumentTitle(parts?: string[]): void {
   const { pathname } = useLocation();
   const params = useParams();
+
   useEffect(() => {
-    let label = TITLES[pathname];
-    if (!label) {
-      if (pathname.startsWith("/notes/") && params.key) {
-        label = prettifyKey(params.key);
+    const explicit = (parts ?? []).filter((p) => typeof p === "string" && p.trim().length > 0);
+    let segments: string[] = [];
+
+    if (explicit.length > 0) {
+      segments = [...explicit, SUFFIX];
+    } else {
+      const label = STATIC_TITLES[pathname];
+      if (label) {
+        segments = [label, SUFFIX];
+      } else if (pathname.startsWith("/notes/") && params.key) {
+        segments = [prettifyKey(params.key), SUFFIX];
       } else if (pathname.startsWith("/docs/") && params.id) {
-        label = `Document ${params.id.slice(0, 8)}`;
+        // Route may pass its own title via `parts`; otherwise show a short id.
+        segments = [`Document ${params.id.slice(0, 8)}`, SUFFIX];
       } else {
-        label = "docsiq";
+        segments = [SUFFIX];
       }
     }
-    document.title = label === "docsiq" ? "docsiq" : `${label} — docsiq`;
-  }, [pathname, params]);
+
+    document.title =
+      segments.length === 1 ? segments[0]! : segments.join(" — ");
+  }, [pathname, params, parts]);
 }
diff --git a/ui/src/hooks/useLastVisit.ts b/ui/src/hooks/useLastVisit.ts
index 02ad0a8..ee8ffe5 100644
--- a/ui/src/hooks/useLastVisit.ts
+++ b/ui/src/hooks/useLastVisit.ts
@@ -1,4 +1,4 @@
-import { useEffect, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 
 const KEY = "docsiq-last-visit";
 
@@ -8,11 +8,16 @@ export function useLastVisit() {
     return v ? Number(v) : 0;
   });
 
-  function touch() {
+  // Stable reference so consumers can safely place `touch` in
+  // useEffect dep arrays without triggering an update loop. Without
+  // useCallback, `touch` is a fresh function every render which, when
+  // used as a cleanup that itself calls setState, causes an infinite
+  // render loop (Maximum update depth exceeded).
+  const touch = useCallback(() => {
     const now = Date.now();
     localStorage.setItem(KEY, String(now));
     setLast(now);
-  }
+  }, []);
 
   return { lastVisit: last, touch };
 }
diff --git a/ui/src/lib/__tests__/motion.test.ts b/ui/src/lib/__tests__/motion.test.ts
new file mode 100644
index 0000000..a971553
--- /dev/null
+++ b/ui/src/lib/__tests__/motion.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+
+function durationOf(t: unknown): number | undefined {
+  return (t as { duration?: number }).duration;
+}
+
+describe("motion presets", () => {
+  beforeEach(() => {
+    // default: user does not prefer reduced motion
+    window.matchMedia = vi.fn().mockImplementation((query: string) => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    }));
+  });
+  afterEach(() => vi.restoreAllMocks());
+
+  it("fade returns non-zero duration when motion is allowed", async () => {
+    const { fadeTransition } = await import("../motion");
+    expect(durationOf(fadeTransition(false))).toBeGreaterThan(0);
+  });
+
+  it("fade returns zero duration when reduced motion is requested", async () => {
+    const { fadeTransition } = await import("../motion");
+    expect(durationOf(fadeTransition(true))).toBe(0);
+  });
+
+  it("slideTransition honours reduced motion too", async () => {
+    const { slideTransition } = await import("../motion");
+    expect(durationOf(slideTransition(true))).toBe(0);
+    expect(durationOf(slideTransition(false))).toBeGreaterThan(0);
+  });
+
+  it("popTransition honours reduced motion too", async () => {
+    const { popTransition } = await import("../motion");
+    expect(durationOf(popTransition(true))).toBe(0);
+    expect(durationOf(popTransition(false))).toBeGreaterThan(0);
+  });
+});
diff --git a/ui/src/lib/motion.ts b/ui/src/lib/motion.ts
index a0dbc30..c378e5b 100644
--- a/ui/src/lib/motion.ts
+++ b/ui/src/lib/motion.ts
@@ -1,5 +1,49 @@
 import type { Transition } from "framer-motion";
 
+/**
+ * Reduced-motion-aware transition presets.
+ *
+ * Callers pass the current user preference (from useReducedMotion()) and
+ * receive a transition config whose duration collapses to 0 when reduced
+ * motion is requested — still completing the state change, just instantly.
+ */
+
+export function fadeTransition(reducedMotion: boolean): Transition {
+  return {
+    duration: reducedMotion ? 0 : 0.18,
+    ease: [0.2, 0, 0, 1],
+  };
+}
+
+export function slideTransition(reducedMotion: boolean): Transition {
+  return {
+    duration: reducedMotion ? 0 : 0.22,
+    ease: [0.2, 0, 0, 1],
+  };
+}
+
+export function popTransition(reducedMotion: boolean): Transition {
+  return {
+    duration: reducedMotion ? 0 : 0.16,
+    ease: [0.2, 0, 0, 1],
+  };
+}
+
+/** Variants helper for simple fade-in mounts. */
+export const fadeInVariants = {
+  hidden: { opacity: 0 },
+  visible: { opacity: 1 },
+};
+
+/** Variants helper for slide-up mounts (12px travel). */
+export const slideUpVariants = {
+  hidden: { opacity: 0, y: 12 },
+  visible: { opacity: 1, y: 0 },
+};
+
+// --- Legacy presets kept for backward compatibility with any existing
+// callers in the tree or in parallel blocks. Prefer the factory functions
+// above in new code (they participate in reduced-motion gating).
 export const enterTransition: Transition = {
   duration: 0.18,
   ease: [0.3, 0, 0, 1],
diff --git a/ui/src/routes/Graph.tsx b/ui/src/routes/Graph.tsx
index 3d798a3..b7b4ab8 100644
--- a/ui/src/routes/Graph.tsx
+++ b/ui/src/routes/Graph.tsx
@@ -1,13 +1,40 @@
 import { GraphCanvas } from "@/components/graph/GraphCanvas";
 import { useNotesGraph } from "@/hooks/api/useGraph";
 import { useProjectStore } from "@/stores/project";
+import { EmptyState, ErrorState, LoadingSkeleton } from "@/components/empty";
 
 export default function Graph() {
   const project = useProjectStore((s) => s.slug);
-  const { data, isLoading } = useNotesGraph(project);
-  if (isLoading) return <div className="p-8 text-sm text-muted-foreground">Loading graph…</div>;
+  const { data, isLoading, error, refetch } = useNotesGraph(project);
+  const err = error as Error | null | undefined;
+
+  if (isLoading) {
+    return (
+      <div className="graph-page p-8">
+        <LoadingSkeleton label="Loading graph" rows={4} />
+      </div>
+    );
+  }
+  if (err) {
+    return (
+      <div className="graph-page p-8">
+        <ErrorState
+          title="Graph failed to load"
+          message={err.message || "Unknown error"}
+          onRetry={() => refetch()}
+        />
+      </div>
+    );
+  }
   if (!data || data.nodes.length === 0) {
-    return <div className="p-8 text-sm text-muted-foreground">No graph data for this project.</div>;
+    return (
+      <div className="graph-page p-8">
+        <EmptyState
+          title="No graph data for this project"
+          description="Ingest or index a document to build the graph."
+        />
+      </div>
+    );
   }
   return (
     <div className="graph-page">
diff --git a/ui/src/routes/Home.tsx b/ui/src/routes/Home.tsx
index e5712b3..2240f32 100644
--- a/ui/src/routes/Home.tsx
+++ b/ui/src/routes/Home.tsx
@@ -10,6 +10,7 @@ import { useActivity } from "@/hooks/api/useActivity";
 import { useNotes } from "@/hooks/api/useNotes";
 import { useNotesGraph } from "@/hooks/api/useGraph";
 import { useLastVisit } from "@/hooks/useLastVisit";
+import { EmptyState, ErrorState, LoadingSkeleton } from "@/components/empty";
 
 export default function Home() {
   const project = useProjectStore((s) => s.slug);
@@ -36,6 +37,9 @@ export default function Home() {
     return { ...base, notes: notesCount };
   }, [stats.data, notes.data]);
 
+  const activityError = activity.error as Error | null | undefined;
+  const graphError = graph.error as Error | null | undefined;
+
   return (
     <div className="page">
       <StatsStrip stats={mergedStats} delta={{ notes: newCount }} />
@@ -49,7 +53,22 @@ export default function Home() {
             </div>
           </div>
           <div className="page-body">
-            <ActivityFeed events={activity.data ?? []} lastVisit={lastVisit} />
+            {activity.isLoading ? (
+              <LoadingSkeleton label="Loading activity" rows={4} />
+            ) : activityError ? (
+              <ErrorState
+                title="Could not load activity"
+                message={activityError.message || "Unknown error"}
+                onRetry={() => activity.refetch()}
+              />
+            ) : (activity.data?.length ?? 0) === 0 ? (
+              <EmptyState
+                title="No recent activity"
+                description="Ingest a document or create a note to start the feed."
+              />
+            ) : (
+              <ActivityFeed events={activity.data ?? []} lastVisit={lastVisit} />
+            )}
           </div>
         </div>
 
@@ -62,7 +81,22 @@ export default function Home() {
               </Link>
             </div>
             <div className="graph-card">
-              <GlanceView data={graph.data} />
+              {graph.isLoading ? (
+                <LoadingSkeleton label="Loading graph preview" rows={3} />
+              ) : graphError ? (
+                <ErrorState
+                  title="Graph failed"
+                  message={graphError.message || "Unknown error"}
+                  onRetry={() => graph.refetch()}
+                />
+              ) : !graph.data || graph.data.nodes.length === 0 ? (
+                <EmptyState
+                  title="No graph yet"
+                  description="Run an index to see entities and edges."
+                />
+              ) : (
+                <GlanceView data={graph.data} />
+              )}
             </div>
           </section>
 
@@ -73,24 +107,30 @@ export default function Home() {
                 all <ArrowUpRight className="size-3" />
               </Link>
             </div>
-            <ul className="note-list">
-              {recentNotes.map((n) => {
-                const parts = n.key.split("/");
-                const name = parts.pop() ?? n.key;
-                const folder = parts.join("/");
-                return (
-                  <li key={n.key}>
-                    <Link to={`/notes/${encodeURIComponent(n.key)}`} className="note-row">
-                      <span className="note-row-name">{name}</span>
-                      {folder && <span className="note-row-folder">{folder}</span>}
-                    </Link>
-                  </li>
-                );
-              })}
-              {recentNotes.length === 0 && (
-                <li className="px-5 py-4 text-sm text-muted-foreground">No notes yet.</li>
-              )}
-            </ul>
+            {notes.isLoading ? (
+              <LoadingSkeleton label="Loading notes" rows={5} />
+            ) : recentNotes.length === 0 ? (
+              <EmptyState
+                title="No notes yet"
+                description="Create your first note to see it here."
+              />
+            ) : (
+              <ul className="note-list">
+                {recentNotes.map((n) => {
+                  const parts = n.key.split("/");
+                  const name = parts.pop() ?? n.key;
+                  const folder = parts.join("/");
+                  return (
+                    <li key={n.key}>
+                      <Link to={`/notes/${encodeURIComponent(n.key)}`} className="note-row">
+                        <span className="note-row-name">{name}</span>
+                        {folder && <span className="note-row-folder">{folder}</span>}
+                      </Link>
+                    </li>
+                  );
+                })}
+              </ul>
+            )}
           </section>
         </aside>
       </div>
diff --git a/ui/src/routes/MCPConsole.tsx b/ui/src/routes/MCPConsole.tsx
index 064d439..78c5aab 100644
--- a/ui/src/routes/MCPConsole.tsx
+++ b/ui/src/routes/MCPConsole.tsx
@@ -2,6 +2,7 @@ import { useMCP, templateForTool, type MCPTool } from "@/hooks/api/useMCP";
 import { useEffect, useMemo, useState } from "react";
 import { Button } from "@/components/ui/button";
 import { cn } from "@/lib/utils";
+import { EmptyState, ErrorState, LoadingSkeleton } from "@/components/empty";
 
 type ParamType = "string" | "number" | "integer" | "boolean" | "array" | "object";
 
@@ -124,8 +125,21 @@ export default function MCPConsole() {
       </aside>
       <section className="mcp-main">
         {!selected ? (
-          <div className="mcp-content text-sm text-muted-foreground">
-            {tools.length ? "Pick a tool on the left." : "Connecting to MCP…"}
+          <div className="mcp-content">
+            {toolsError ? (
+              <ErrorState
+                title="MCP tools failed to load"
+                message={toolsError}
+                onRetry={() => void refreshTools()}
+              />
+            ) : tools.length === 0 ? (
+              <LoadingSkeleton label="Loading MCP tools" rows={4} />
+            ) : (
+              <EmptyState
+                title="Pick a tool"
+                description="Select a tool from the left sidebar to run it."
+              />
+            )}
           </div>
         ) : (
           <div className="mcp-content">
diff --git a/ui/src/routes/__tests__/Home.test.tsx b/ui/src/routes/__tests__/Home.test.tsx
index e2e0a1b..bd88214 100644
--- a/ui/src/routes/__tests__/Home.test.tsx
+++ b/ui/src/routes/__tests__/Home.test.tsx
@@ -23,7 +23,11 @@ describe("Home route", () => {
       http.get("/api/projects/_default/graph", () => HttpResponse.json({ nodes: [], edges: [] })),
     );
     render(wrap()(<Home />));
-    await waitFor(() => expect(screen.getByText(/since your last visit|nothing new/i)).toBeInTheDocument());
+    await waitFor(() =>
+      expect(
+        screen.getByText(/no recent activity|since your last visit|nothing new/i),
+      ).toBeInTheDocument(),
+    );
     expect(screen.getByRole("region", { name: /project statistics/i })).toBeInTheDocument();
   });
 });
diff --git a/ui/src/routes/documents/DocumentView.tsx b/ui/src/routes/documents/DocumentView.tsx
index f21b6f2..5ef22d0 100644
--- a/ui/src/routes/documents/DocumentView.tsx
+++ b/ui/src/routes/documents/DocumentView.tsx
@@ -1,13 +1,46 @@
 import { useParams } from "react-router-dom";
 import { useDoc } from "@/hooks/api/useDocs";
 import { useProjectStore } from "@/stores/project";
+import { EmptyState, ErrorState, LoadingSkeleton } from "@/components/empty";
+import { useDocumentTitle } from "@/hooks/useDocumentTitle";
 
 export default function DocumentView() {
   const { id } = useParams();
   const project = useProjectStore((s) => s.slug);
-  const { data, isLoading } = useDoc(project, id);
-  if (isLoading) return <div className="p-8 text-sm text-muted-foreground">Loading…</div>;
-  if (!data) return <div className="p-8 text-sm">Not found.</div>;
+  const { data, isLoading, error, refetch } = useDoc(project, id);
+  const err = error as Error | null | undefined;
+
+  const docLabel = data?.title || data?.path;
+  useDocumentTitle(docLabel ? [docLabel, "Documents"] : undefined);
+
+  if (isLoading) {
+    return (
+      <div className="p-8 max-w-[620px] mx-auto">
+        <LoadingSkeleton label="Loading document" rows={5} />
+      </div>
+    );
+  }
+  if (err) {
+    return (
+      <div className="p-8 max-w-[620px] mx-auto">
+        <ErrorState
+          title="Document failed to load"
+          message={err.message || "Unknown error"}
+          onRetry={() => refetch()}
+        />
+      </div>
+    );
+  }
+  if (!data) {
+    return (
+      <div className="p-8 max-w-[620px] mx-auto">
+        <EmptyState
+          title="Document not found"
+          description="The document may have been deleted."
+        />
+      </div>
+    );
+  }
   return (
     <article className="doc-view">
       <h1 className="doc-view-title">{data.title || data.path}</h1>
diff --git a/ui/src/routes/documents/DocumentsList.tsx b/ui/src/routes/documents/DocumentsList.tsx
index 8475195..8225a35 100644
--- a/ui/src/routes/documents/DocumentsList.tsx
+++ b/ui/src/routes/documents/DocumentsList.tsx
@@ -6,37 +6,15 @@ import { formatRelativeTime } from "@/lib/format";
 import { Button } from "@/components/ui/button";
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";
 import { UploadModal } from "./UploadModal";
+import { EmptyState, ErrorState, LoadingSkeleton } from "@/components/empty";
 
 export default function DocumentsList() {
   const project = useProjectStore((s) => s.slug);
-  const { data = [] } = useDocs(project);
+  const { data, isLoading, error, refetch } = useDocs(project);
+  const docs = data ?? [];
+  const err = error as Error | null | undefined;
   const [uploadOpen, setUploadOpen] = useState(false);
 
-  if (data.length === 0) {
-    return (
-      <div className="docs-page">
-        <div className="docs-page-head">
-          <h1 className="docs-page-title">Documents</h1>
-          <Button onClick={() => setUploadOpen(true)}>Upload</Button>
-        </div>
-        <UploadModal open={uploadOpen} onOpenChange={setUploadOpen} />
-        <div className="docs-empty">
-          <p className="docs-empty-title">No documents indexed yet.</p>
-          <p className="docs-empty-desc">
-            docsiq indexes from disk or URL into a GraphRAG knowledge base. Run the CLI against a
-            folder of PDFs, Markdown, text, or a docs site.
-          </p>
-          <code className="docs-empty-code">docsiq index ~/path/to/docs --project {project}</code>
-          <p className="docs-empty-hint">
-            Requires an LLM provider (Azure OpenAI / OpenAI / Ollama) configured in
-            <code className="mx-1 px-1 py-0.5 bg-muted rounded font-mono">~/.docsiq/config.yaml</code>.
-            Notes and wikilinks work without a provider.
-          </p>
-        </div>
-      </div>
-    );
-  }
-
   return (
     <div className="docs-page">
       <div className="docs-page-head">
@@ -44,30 +22,47 @@ export default function DocumentsList() {
         <Button onClick={() => setUploadOpen(true)}>Upload</Button>
       </div>
       <UploadModal open={uploadOpen} onOpenChange={setUploadOpen} />
-      <Table>
-        <TableHeader>
-          <TableRow>
-            <TableHead>Title</TableHead>
-            <TableHead>Type</TableHead>
-            <TableHead>Updated</TableHead>
-          </TableRow>
-        </TableHeader>
-        <TableBody>
-          {data.map((d) => (
-            <TableRow key={d.id}>
-              <TableCell>
-                <Link to={`/docs/${d.id}`} className="text-foreground underline decoration-dotted">
-                  {d.title || d.path}
-                </Link>
-              </TableCell>
-              <TableCell className="text-muted-foreground">{d.doc_type}</TableCell>
-              <TableCell className="text-muted-foreground">
-                {formatRelativeTime(d.updated_at * 1000)}
-              </TableCell>
-            </TableRow>
-          ))}
-        </TableBody>
-      </Table>
+      {isLoading ? (
+        <LoadingSkeleton label="Loading documents" rows={6} />
+      ) : err ? (
+        <ErrorState
+          title="Documents failed to load"
+          message={err.message || "Unknown error"}
+          onRetry={() => refetch()}
+        />
+      ) : docs.length === 0 ? (
+        <EmptyState
+          title="No documents yet"
+          description="Upload a PDF, DOCX, or web page to get started."
+        />
+      ) : (
+        <div className="table-scroll">
+          <Table>
+            <TableHeader>
+              <TableRow>
+                <TableHead>Title</TableHead>
+                <TableHead>Type</TableHead>
+                <TableHead>Updated</TableHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {docs.map((d) => (
+                <TableRow key={d.id}>
+                  <TableCell>
+                    <Link to={`/docs/${d.id}`} className="text-foreground underline decoration-dotted">
+                      {d.title || d.path}
+                    </Link>
+                  </TableCell>
+                  <TableCell className="text-muted-foreground">{d.doc_type}</TableCell>
+                  <TableCell className="text-muted-foreground">
+                    {formatRelativeTime(d.updated_at * 1000)}
+                  </TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        </div>
+      )}
     </div>
   );
 }
diff --git a/ui/src/routes/notes/NoteView.tsx b/ui/src/routes/notes/NoteView.tsx
index fad1ef4..e32bfed 100644
--- a/ui/src/routes/notes/NoteView.tsx
+++ b/ui/src/routes/notes/NoteView.tsx
@@ -3,20 +3,45 @@ import { MarkdownView } from "@/components/notes/MarkdownView";
 import { useNote } from "@/hooks/api/useNotes";
 import { useProjectStore } from "@/stores/project";
 import { formatRelativeTime } from "@/lib/format";
+import { EmptyState, ErrorState, LoadingSkeleton } from "@/components/empty";
+import { useDocumentTitle } from "@/hooks/useDocumentTitle";
 
 export default function NoteView() {
   const { key } = useParams();
   const project = useProjectStore((s) => s.slug);
-  const { data: note, isLoading, error } = useNote(project, key);
+  const { data: note, isLoading, error, refetch } = useNote(project, key);
+  const err = error as Error | null | undefined;
+
+  const noteLabel =
+    note?.key?.split("/").pop() ??
+    (key ? decodeURIComponent(key).split("/").pop() : undefined);
+  useDocumentTitle(noteLabel ? [noteLabel, "Notes"] : undefined);
 
   if (isLoading) {
-    return <div className="p-8 text-muted-foreground text-sm">Loading…</div>;
+    return (
+      <div className="p-8 max-w-[620px] mx-auto">
+        <LoadingSkeleton label="Loading note" rows={5} />
+      </div>
+    );
+  }
+  if (err) {
+    return (
+      <div className="p-8 max-w-[620px] mx-auto">
+        <ErrorState
+          title="Note failed to load"
+          message={err.message || "Unknown error"}
+          onRetry={() => refetch()}
+        />
+      </div>
+    );
   }
-  if (error || !note) {
+  if (!note) {
     return (
       <div className="p-8 max-w-[620px] mx-auto">
-        <h1 className="text-xl font-semibold">Note not found</h1>
-        <p className="text-sm text-muted-foreground mt-2 font-mono">{key}</p>
+        <EmptyState
+          title="Note not found"
+          description="The note may have been deleted or the link is stale."
+        />
       </div>
     );
   }
diff --git a/ui/src/routes/notes/NotesLayout.tsx b/ui/src/routes/notes/NotesLayout.tsx
index 3ed413f..e3ca1a2 100644
--- a/ui/src/routes/notes/NotesLayout.tsx
+++ b/ui/src/routes/notes/NotesLayout.tsx
@@ -5,6 +5,7 @@ import { LinkPanel } from "@/components/notes/LinkPanel";
 import { useProjectStore } from "@/stores/project";
 import { useHotkey } from "@/hooks/useHotkey";
 import { useNotes } from "@/hooks/api/useNotes";
+import { EmptyState, ErrorState, LoadingSkeleton } from "@/components/empty";
 
 export default function NotesLayout() {
   const project = useProjectStore((s) => s.slug);
@@ -26,7 +27,8 @@ export default function NotesLayout() {
 }
 
 function NotesIndex({ project }: { project: string }) {
-  const { data, isLoading } = useNotes(project);
+  const { data, isLoading, error, refetch } = useNotes(project);
+  const err = error as Error | null | undefined;
   const groups = useMemo(() => {
     const byFolder: Record<string, string[]> = {};
     for (const n of data ?? []) {
@@ -50,24 +52,39 @@ function NotesIndex({ project }: { project: string }) {
         Open tree <kbd className="kbd">⌘/</kbd>
         &nbsp;· search <kbd className="kbd">⌘K</kbd>
       </p>
-      <div className="notes-index-grid">
-        {groups.map(([folder, keys]) => (
-          <section key={folder} className="notes-folder">
-            <h2 className="notes-folder-head">
-              {folder} <span className="notes-folder-count">· {keys.length}</span>
-            </h2>
-            <ul className="notes-folder-list">
-              {keys.map((k) => (
-                <li key={k} className="notes-folder-item">
-                  <Link to={`/notes/${encodeURIComponent(k)}`} className="notes-folder-link">
-                    {k.split("/").pop()}
-                  </Link>
-                </li>
-              ))}
-            </ul>
-          </section>
-        ))}
-      </div>
+      {isLoading ? (
+        <LoadingSkeleton label="Loading notes" rows={6} />
+      ) : err ? (
+        <ErrorState
+          title="Notes failed to load"
+          message={err.message || "Unknown error"}
+          onRetry={() => refetch()}
+        />
+      ) : groups.length === 0 ? (
+        <EmptyState
+          title="No notes yet"
+          description="Create your first note to see it here."
+        />
+      ) : (
+        <div className="notes-index-grid">
+          {groups.map(([folder, keys]) => (
+            <section key={folder} className="notes-folder">
+              <h2 className="notes-folder-head">
+                {folder} <span className="notes-folder-count">· {keys.length}</span>
+              </h2>
+              <ul className="notes-folder-list">
+                {keys.map((k) => (
+                  <li key={k} className="notes-folder-item">
+                    <Link to={`/notes/${encodeURIComponent(k)}`} className="notes-folder-link">
+                      {k.split("/").pop()}
+                    </Link>
+                  </li>
+                ))}
+              </ul>
+            </section>
+          ))}
+        </div>
+      )}
     </div>
   );
 }
diff --git a/ui/src/routes/notes/NotesSearch.tsx b/ui/src/routes/notes/NotesSearch.tsx
index e32ac54..9ca397a 100644
--- a/ui/src/routes/notes/NotesSearch.tsx
+++ b/ui/src/routes/notes/NotesSearch.tsx
@@ -5,6 +5,7 @@ import { apiFetch } from "@/lib/api-client";
 import { qk } from "@/hooks/api/keys";
 import { useProjectStore } from "@/stores/project";
 import type { NoteHit } from "@/types/api";
+import { EmptyState, ErrorState, LoadingSkeleton } from "@/components/empty";
 
 export default function NotesSearch() {
   const project = useProjectStore((s) => s.slug);
@@ -16,7 +17,7 @@ export default function NotesSearch() {
     return () => clearTimeout(t);
   }, [q]);
 
-  const { data, isFetching } = useQuery({
+  const { data, isFetching, error, refetch } = useQuery({
     queryKey: qk.notesSearch(project, debounced),
     enabled: debounced.length > 0,
     queryFn: () =>
@@ -24,6 +25,7 @@ export default function NotesSearch() {
         `/api/projects/${encodeURIComponent(project)}/search?q=${encodeURIComponent(debounced)}`,
       ),
   });
+  const err = error as Error | null | undefined;
 
   return (
     <div className="notes-search">
@@ -35,23 +37,39 @@ export default function NotesSearch() {
         className="notes-search-input"
         aria-label="Search notes"
       />
-      {isFetching && <p className="text-xs text-muted-foreground mt-2">searching…</p>}
-      <ul className="mt-6 space-y-1.5">
-        {data?.hits.map((h) => (
-          <li key={h.key}>
-            <Link
-              to={`/notes/${encodeURIComponent(h.key)}`}
-              className="notes-search-hit"
-            >
-              <div className="notes-search-hit-title">{h.key}</div>
-              <div
-                className="notes-search-hit-snippet"
-                dangerouslySetInnerHTML={{ __html: h.snippet }}
-              />
-            </Link>
-          </li>
-        ))}
-      </ul>
+      <div className="mt-6">
+        {debounced.length === 0 ? null : isFetching ? (
+          <LoadingSkeleton label="Searching notes" rows={4} />
+        ) : err ? (
+          <ErrorState
+            title="Search failed"
+            message={err.message || "Unknown error"}
+            onRetry={() => refetch()}
+          />
+        ) : (data?.hits.length ?? 0) === 0 ? (
+          <EmptyState
+            title="No results"
+            description={`No notes match "${debounced}".`}
+          />
+        ) : (
+          <ul className="space-y-1.5">
+            {data?.hits.map((h) => (
+              <li key={h.key}>
+                <Link
+                  to={`/notes/${encodeURIComponent(h.key)}`}
+                  className="notes-search-hit"
+                >
+                  <div className="notes-search-hit-title">{h.key}</div>
+                  <div
+                    className="notes-search-hit-snippet"
+                    dangerouslySetInnerHTML={{ __html: h.snippet }}
+                  />
+                </Link>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
     </div>
   );
 }
diff --git a/ui/src/styles/globals.css b/ui/src/styles/globals.css
index bf633c1..eef577b 100644
--- a/ui/src/styles/globals.css
+++ b/ui/src/styles/globals.css
@@ -23,8 +23,11 @@
   --border: oklch(0.92 0.005 260);
   --input: oklch(0.92 0.005 260);
 
-  /* Brand — Supabase green, tuned for light bg */
-  --primary: oklch(0.68 0.16 152);
+  /* Brand — Supabase green, tuned for light bg.
+     Primary darkened from 0.68 to 0.52 for WCAG AA 4.5:1 contrast with
+     white primary-foreground (now ~5.1:1). Ring intentionally kept
+     brighter since ring color is a focus outline, not text. */
+  --primary: oklch(0.52 0.16 152);
   --primary-foreground: oklch(1 0 0);
   --ring: oklch(0.68 0.16 152);
 
@@ -469,3 +472,121 @@ html, body {
   /* ── Command palette item icon chips ─────────────────────── */
   .cmd-chip            { @apply font-mono text-[10px] px-1.5 mr-2 rounded bg-muted text-muted-foreground; }
 }
+
+/* Block 5.2 — reusable state trio ------------------------------------ */
+.state-card {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 2rem 1.5rem;
+  border: 1px solid var(--border);
+  border-radius: 0.75rem;
+  background: var(--card);
+  text-align: center;
+}
+.state-card__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2.5rem;
+  height: 2.5rem;
+  border-radius: 9999px;
+  background: color-mix(in oklab, var(--muted) 60%, transparent);
+  color: var(--muted-foreground);
+}
+.state-card__icon--danger {
+  background: color-mix(in oklab, var(--destructive) 14%, transparent);
+  color: var(--destructive);
+}
+.state-card__title {
+  font-size: 0.95rem;
+  font-weight: 600;
+  color: var(--foreground);
+}
+.state-card__description {
+  font-size: 0.85rem;
+  line-height: 1.45;
+  color: var(--muted-foreground);
+  max-width: 40ch;
+}
+.state-card__action {
+  margin-top: 0.5rem;
+}
+.state-card__bars {
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+.state-card__bar {
+  height: 0.75rem;
+  width: 100%;
+  border-radius: 0.375rem;
+}
+.state-card--loading { padding: 1.25rem; align-items: stretch; }
+
+/* Block 5.4 — iOS safe-area insets ------------------------------------- */
+:root {
+  --header-pad: 1rem;
+}
+
+/* Header padding respects the notch on iOS */
+.site-header {
+  padding-top: max(var(--header-pad), env(safe-area-inset-top));
+  padding-right: max(var(--header-pad), env(safe-area-inset-right));
+}
+
+/* Sidebar padding respects the left inset in landscape iOS */
+[data-slot="sidebar-container"],
+[data-sidebar="sidebar"] {
+  padding-left: env(safe-area-inset-left);
+}
+
+/* Main content also respects bottom inset for iOS home indicator */
+main#main {
+  padding-bottom: env(safe-area-inset-bottom);
+}
+
+/* Block 5.7 — reduced motion ------------------------------------------- */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.001ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.001ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+/* Block 5.10 — mobile viewport pass ------------------------------------ */
+@media (max-width: 480px) {
+  .site-header button,
+  .site-header a[role="button"],
+  .site-header-reload,
+  .site-header-mobile-trigger,
+  .site-header-search {
+    min-height: 44px;
+    min-width: 44px;
+  }
+  /* Command palette fills viewport under 480px */
+  [role="dialog"][data-slot="dialog-content"],
+  [cmdk-root] {
+    width: 100vw !important;
+    max-width: 100vw !important;
+    height: 100vh !important;
+    max-height: 100vh !important;
+    border-radius: 0 !important;
+  }
+}
+
+/* Tables scroll horizontally inside a scroll container, not the body */
+.table-scroll {
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
+  max-width: 100%;
+}
+.table-scroll > table {
+  min-width: max-content;
+}