From 32de518670060c89f71c9150beb6da0d4949994a Mon Sep 17 00:00:00 2001
From: Kody Sale <kody.sale@gmail.com>
Date: Mon, 8 Jun 2026 15:37:42 -0700
Subject: [PATCH 1/4] Add Obol-branded dark mode with a light/dark toggle.

---
 components/assessment/AssessmentApp.tsx |  2 +
 components/assessment/ThemeToggle.tsx   | 44 +++++++++++++++++++
 components/assessment/stitches.ts       | 15 +++++++
 components/pizza/Pizza.tsx              | 34 ++++++++++-----
 hooks/useTheme.ts                       | 58 +++++++++++++++++++++++++
 pages/_document.tsx                     |  6 +++
 pages/methodology.tsx                   |  4 ++
 styles/theme-tokens.css                 | 52 ++++++++++++++++++++++
 8 files changed, 204 insertions(+), 11 deletions(-)
 create mode 100644 components/assessment/ThemeToggle.tsx
 create mode 100644 hooks/useTheme.ts

diff --git a/components/assessment/AssessmentApp.tsx b/components/assessment/AssessmentApp.tsx
index 9cda7c3..4e17dd0 100644
--- a/components/assessment/AssessmentApp.tsx
+++ b/components/assessment/AssessmentApp.tsx
@@ -18,6 +18,7 @@ import {
 } from "./Blockers";
 import { Intro } from "./Intro";
 import { Question } from "./Question";
+import { ThemeToggle } from "./ThemeToggle";
 import { LevelUp, ResultHero, ShareModal } from "./Results";
 import {
   BrandAccent,
@@ -122,6 +123,7 @@ export function AssessmentApp({ initialShareCode }: AssessmentAppProps) {
         <Link href="/methodology/" passHref legacyBehavior>
           <TopNavLink>Methodology</TopNavLink>
         </Link>
+        <ThemeToggle />
       </TopBar>
 
       <MainGrid>
diff --git a/components/assessment/ThemeToggle.tsx b/components/assessment/ThemeToggle.tsx
new file mode 100644
index 0000000..7582ed5
--- /dev/null
+++ b/components/assessment/ThemeToggle.tsx
@@ -0,0 +1,44 @@
+import { useTheme } from "@hooks/useTheme";
+import { ThemeToggleButton } from "./stitches";
+
+const SunIcon = () => (
+  <svg
+    width="16"
+    height="16"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    aria-hidden="true"
+  >
+    <circle cx="12" cy="12" r="4" />
+    <path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4" />
+  </svg>
+);
+
+const MoonIcon = () => (
+  <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+    <path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8z" />
+  </svg>
+);
+
+/**
+ * Sun/moon button that flips light/dark. Renders the light-mode (moon) icon
+ * until mounted so it never mismatches the server-rendered markup.
+ */
+export function ThemeToggle() {
+  const { theme, toggle, mounted } = useTheme();
+  const isDark = theme === "dark";
+
+  return (
+    <ThemeToggleButton
+      type="button"
+      onClick={toggle}
+      aria-label={isDark ? "Switch to light mode" : "Switch to dark mode"}
+      title={isDark ? "Switch to light mode" : "Switch to dark mode"}
+    >
+      {mounted && isDark ? <SunIcon /> : <MoonIcon />}
+    </ThemeToggleButton>
+  );
+}
diff --git a/components/assessment/stitches.ts b/components/assessment/stitches.ts
index a16b2ba..7ab9f54 100644
--- a/components/assessment/stitches.ts
+++ b/components/assessment/stitches.ts
@@ -78,6 +78,21 @@ export const TopNavLink = styled("a", {
   "&:hover": { color: "$body" },
 });
 
+export const ThemeToggleButton = styled("button", {
+  all: "unset",
+  cursor: "pointer",
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center",
+  width: 30,
+  height: 30,
+  borderRadius: "$round",
+  color: "$textMiddle",
+  border: "1px solid $bg05",
+  "&:hover": { color: "$body", backgroundColor: "$bg04" },
+  "&:focus-visible": { outline: "2px solid var(--theme-brand)", outlineOffset: 2 },
+});
+
 export const MainGrid = styled(Box, {
   flex: 1,
   minHeight: 0,
diff --git a/components/pizza/Pizza.tsx b/components/pizza/Pizza.tsx
index a687906..a4f701b 100644
--- a/components/pizza/Pizza.tsx
+++ b/components/pizza/Pizza.tsx
@@ -1,13 +1,25 @@
 import { SLICES } from "@lib/rubric";
-import type { Answers, SliceId, Stage } from "@lib/rubric/types";
-import {
-  PIZZA_EMPTY,
-  PIZZA_EMPTY_STROKE,
-  PIZZA_FILL,
-  PIZZA_INK,
-  PIZZA_PLATE,
-  PIZZA_RING,
-} from "@lib/theme/tokens";
+import type { Answers, SliceColor, SliceId, Stage } from "@lib/rubric/types";
+
+/**
+ * Theme-reactive colors. The in-app pizza reads CSS variables so it follows
+ * light/dark mode; the static OG share images use the hex constants in
+ * lib/theme/tokens.ts instead (they're pre-rendered at build time).
+ */
+const PIZZA_FILL: Record<SliceColor, string> = {
+  green: "var(--vb-green)",
+  yellow: "var(--vb-yellow)",
+  red: "var(--vb-red)",
+};
+const PIZZA_RING: Record<SliceColor, string> = {
+  green: "var(--theme-risk-green-ring)",
+  yellow: "var(--theme-risk-yellow-ring)",
+  red: "var(--theme-risk-red-ring)",
+};
+const PIZZA_PLATE = "var(--vb-plate)";
+const PIZZA_EMPTY = "var(--vb-empty)";
+const PIZZA_EMPTY_STROKE = "var(--vb-empty-stroke)";
+const PIZZA_INK = "var(--vb-ink)";
 
 const RAD = Math.PI / 180;
 
@@ -235,7 +247,7 @@ export function Pizza({
               className="vbpizza__progress"
               style={{
                 fill: "none",
-                stroke: ringTone || "#9cc2c9",
+                stroke: ringTone || "var(--ice)",
                 strokeWidth: 3.5,
                 strokeLinecap: frac >= 1 ? "butt" : "round",
                 strokeDasharray:
@@ -257,7 +269,7 @@ export function Pizza({
             y={cy - size * 0.028}
             className="vbpizza__stagek"
             textAnchor="middle"
-            style={{ fontSize: size * 0.033 }}
+            style={{ fill: PIZZA_INK, fontSize: size * 0.033 }}
           >
             STAGE
           </text>
diff --git a/hooks/useTheme.ts b/hooks/useTheme.ts
new file mode 100644
index 0000000..5cc7184
--- /dev/null
+++ b/hooks/useTheme.ts
@@ -0,0 +1,58 @@
+import { useEffect, useState } from "react";
+
+export type Theme = "light" | "dark";
+
+const STORAGE_KEY = "vb-theme";
+
+function applyTheme(theme: Theme) {
+  const root = document.documentElement;
+  if (theme === "dark") {
+    root.setAttribute("data-theme", "dark");
+  } else {
+    root.removeAttribute("data-theme");
+  }
+}
+
+/**
+ * Light/dark theme state, persisted to localStorage and reflected as
+ * data-theme on <html>. Defaults to light. The pre-paint script in
+ * _document.tsx sets the attribute before hydration to avoid a flash;
+ * this hook syncs React state to it on mount.
+ */
+export function useTheme() {
+  // Match the server-rendered markup (light) on first client render, then
+  // reconcile to the persisted choice in the effect below — no hydration gap.
+  const [theme, setTheme] = useState<Theme>("light");
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    let stored: Theme | null = null;
+    try {
+      stored = localStorage.getItem(STORAGE_KEY) as Theme | null;
+    } catch {
+      stored = null;
+    }
+    const current =
+      stored ??
+      (document.documentElement.getAttribute("data-theme") === "dark"
+        ? "dark"
+        : "light");
+    setTheme(current);
+    setMounted(true);
+  }, []);
+
+  const toggle = () => {
+    setTheme((prev) => {
+      const next: Theme = prev === "dark" ? "light" : "dark";
+      applyTheme(next);
+      try {
+        localStorage.setItem(STORAGE_KEY, next);
+      } catch {
+        /* private mode / storage disabled — theme still applies for the session */
+      }
+      return next;
+    });
+  };
+
+  return { theme, toggle, mounted };
+}
diff --git a/pages/_document.tsx b/pages/_document.tsx
index 8fd08be..aa12d6b 100644
--- a/pages/_document.tsx
+++ b/pages/_document.tsx
@@ -15,6 +15,12 @@ export default function Document() {
   return (
     <Html lang="en">
       <Head>
+        <script
+          dangerouslySetInnerHTML={{
+            __html:
+              "(function(){try{if(localStorage.getItem('vb-theme')==='dark')document.documentElement.setAttribute('data-theme','dark');}catch(e){}})();",
+          }}
+        />
         <style id="obol" dangerouslySetInnerHTML={{ __html: getCssText() }} />
         <link rel="icon" type="image/svg+xml" href={`${BASE_PATH}/icon.svg`} />
         <link rel="icon" type="image/png" sizes="32x32" href={`${BASE_PATH}/favicon-32.png`} />
diff --git a/pages/methodology.tsx b/pages/methodology.tsx
index bf90ce4..20398a7 100644
--- a/pages/methodology.tsx
+++ b/pages/methodology.tsx
@@ -4,7 +4,9 @@ import {
   BrandLink,
   TagPill,
   TopBar,
+  TopSpacer,
 } from "@components/assessment/stitches";
+import { ThemeToggle } from "@components/assessment/ThemeToggle";
 import { SLICES } from "@lib/rubric";
 import type { GetStaticProps } from "next";
 
@@ -18,6 +20,8 @@ export default function MethodologyPage() {
           </BrandLink>
         </Link>
         <TagPill>v0.1 · methodology</TagPill>
+        <TopSpacer />
+        <ThemeToggle />
       </TopBar>
 
       <main className="vb-methodology__main">
diff --git a/styles/theme-tokens.css b/styles/theme-tokens.css
index ae96599..1b2974a 100644
--- a/styles/theme-tokens.css
+++ b/styles/theme-tokens.css
@@ -50,6 +50,58 @@
   --theme-pizza-ink: #000000;
 }
 
+/* =============================================================================
+   DARK THEME — Obol-branded dark palette, mirrors the standalone prototype.
+   Activated by data-theme="dark" on <html> (see hooks/useTheme + _document).
+   Overrides the --theme-* source values; the alias layer below recomputes
+   automatically. --bg-01..05 are re-pointed past obol-ui's --colors-* tokens.
+   ============================================================================= */
+:root[data-theme="dark"] {
+  /* ---- Brand accent (bright mint reads on dark surfaces) ---- */
+  --theme-brand: #2fe4ab;          /* obolGreen */
+  --theme-brand-hover: #0f7c76;
+  --theme-brand-highlight: #b6ea5c; /* lime */
+
+  /* ---- Page surfaces ---- */
+  --theme-surface-page: #091011;
+  --theme-surface-card: #111f22;
+  --theme-surface-panel: #182d32;
+  --theme-surface-hover: #243d42;
+  --theme-border: #2d4d53;
+  --theme-border-strong: #3a5f66;
+
+  /* ---- Text ---- */
+  --theme-text-primary: #e1e9eb;
+  --theme-text-secondary: #97b2b8;
+  --theme-text-muted: #667a80;
+  --theme-text-faint: #475e64;
+  --theme-text-on-brand: #091011;
+
+  /* ---- Pizza / risk slices ---- */
+  --theme-risk-green: #2fe4ab;
+  --theme-risk-yellow: #e8b339;
+  --theme-risk-red: #dd603c;
+  --theme-risk-green-ring: #6ff0c8;
+  --theme-risk-yellow-ring: #f0c95f;
+  --theme-risk-red-ring: #e8856a;
+
+  /* ---- Pizza plate / empty wedge ---- */
+  --theme-pizza-plate: #0a1214;
+  --theme-pizza-empty: #16282d;
+  --theme-pizza-empty-stroke: #2d4d53;
+  --theme-pizza-ink: #e1e9eb;
+
+  /* Re-point surface aliases past obol-ui's scoped --colors-* tokens. */
+  --bg-01: var(--theme-surface-page);
+  --bg-02: var(--theme-surface-card);
+  --bg-03: var(--theme-surface-panel);
+  --bg-04: var(--theme-surface-hover);
+  --bg-05: var(--theme-border);
+
+  /* --ice diverges from brand in the dark palette (muted ice-blue). */
+  --ice: #9cc2c9;
+}
+
 /* ---- App aliases (handoff CSS; mirror obol-ui $bg01 / $obolGreen tokens) ---- */
 :root {
   --bg-01: var(--colors-bg01, var(--theme-surface-page));

From 29153aba2c46d9931f46ef30f2d695c2e85e27bc Mon Sep 17 00:00:00 2001
From: Kody Sale <kody.sale@gmail.com>
Date: Mon, 8 Jun 2026 15:39:37 -0700
Subject: [PATCH 2/4] Center stage-ladder pill labels vertically.

---
 components/assessment/stitches.ts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/components/assessment/stitches.ts b/components/assessment/stitches.ts
index 7ab9f54..fd43d70 100644
--- a/components/assessment/stitches.ts
+++ b/components/assessment/stitches.ts
@@ -277,12 +277,13 @@ export const LadderName = styled(Text, {
 export const LadderKind = styled(Text, {
   fontSize: "9.5px",
   fontWeight: "$bold",
+  lineHeight: 1,
   textTransform: "uppercase",
   letterSpacing: "0.07em",
   color: "$textMiddle",
   border: "1px solid $bg05",
   borderRadius: "$pill",
-  padding: "1px 7px",
+  padding: "3px 7px",
   variants: {
     tone: {
       red: { color: risk.red, borderColor: risk.redB },
@@ -295,9 +296,10 @@ export const LadderKind = styled(Text, {
 export const LadderHere = styled(Text, {
   fontSize: "9.5px",
   fontWeight: "$bold",
+  lineHeight: 1,
   textTransform: "uppercase",
   letterSpacing: "0.06em",
-  padding: "2px 8px",
+  padding: "3px 8px",
   borderRadius: "$pill",
   whiteSpace: "nowrap",
   variants: {

From ff09206c1af1cc92830f5ab1bff06f80c0928563 Mon Sep 17 00:00:00 2001
From: Kody Sale <kody.sale@gmail.com>
Date: Mon, 8 Jun 2026 15:40:30 -0700
Subject: [PATCH 3/4] Let users return to the intro from the first question.

---
 components/assessment/AssessmentApp.tsx | 2 +-
 components/assessment/Question.tsx      | 2 +-
 hooks/useAssessment.ts                  | 3 +++
 3 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/components/assessment/AssessmentApp.tsx b/components/assessment/AssessmentApp.tsx
index 4e17dd0..42a21cf 100644
--- a/components/assessment/AssessmentApp.tsx
+++ b/components/assessment/AssessmentApp.tsx
@@ -137,7 +137,7 @@ export function AssessmentApp({ initialShareCode }: AssessmentAppProps) {
               onChoose={choose}
               index={a.step}
               total={a.total}
-              onBack={a.back}
+              onBack={a.step === 0 ? a.toIntro : a.back}
               onShowResults={
                 allAnswered(a.answers) ? a.showResults : undefined
               }
diff --git a/components/assessment/Question.tsx b/components/assessment/Question.tsx
index b0b298f..0edc8ed 100644
--- a/components/assessment/Question.tsx
+++ b/components/assessment/Question.tsx
@@ -103,7 +103,7 @@ export function Question({
           )}
         </QuestionRisk>
       )}
-      {index > 0 && onBack && (
+      {onBack && (
         <BackButton type="button" onClick={onBack}>
           ← Back
         </BackButton>
diff --git a/hooks/useAssessment.ts b/hooks/useAssessment.ts
index 460e9fa..98bc04f 100644
--- a/hooks/useAssessment.ts
+++ b/hooks/useAssessment.ts
@@ -44,6 +44,8 @@ export function useAssessment() {
 
   const start = useCallback(() => setStarted(true), []);
   const back = useCallback(() => setStep((s) => Math.max(s - 1, 0)), []);
+  /** Return to the intro screen, keeping answers and step so progress resumes. */
+  const toIntro = useCallback(() => setStarted(false), []);
   const goto = useCallback((i: number) => {
     setStarted(true);
     setStep(Math.max(0, Math.min(i, total)));
@@ -87,6 +89,7 @@ export function useAssessment() {
     total,
     choose,
     back,
+    toIntro,
     goto,
     showResults,
     takeResultsConfetti,

From 788d214d38e02364790ffab56adc0a316691b1f6 Mon Sep 17 00:00:00 2001
From: HananINouman <hanan@obol.tech>
Date: Tue, 9 Jun 2026 14:17:03 +0300
Subject: [PATCH 4/4] Switch dark mode to next-themes and fix dev hydration
 warnings.

Replace the hand-rolled theme hook with next-themes, modernize Link usage, and gate the theme toggle until mount so SSR and client markup stay in sync.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 components/AppThemeProvider.tsx         | 13 ++++++
 components/assessment/AssessmentApp.tsx | 13 ++----
 components/assessment/ThemeToggle.tsx   | 13 ++++--
 components/assessment/stitches.ts       |  5 ++-
 components/layout/Navbar.tsx            | 39 ++++++++---------
 components/pizza/Pizza.tsx              |  4 +-
 hooks/useTheme.ts                       | 58 -------------------------
 package.json                            |  1 +
 pages/_app.tsx                          | 18 +++++---
 pages/_document.tsx                     |  8 +---
 pages/methodology.tsx                   |  8 ++--
 styles/theme-tokens.css                 |  2 +-
 yarn.lock                               |  5 +++
 13 files changed, 74 insertions(+), 113 deletions(-)
 create mode 100644 components/AppThemeProvider.tsx
 delete mode 100644 hooks/useTheme.ts

diff --git a/components/AppThemeProvider.tsx b/components/AppThemeProvider.tsx
new file mode 100644
index 0000000..fb2b4bb
--- /dev/null
+++ b/components/AppThemeProvider.tsx
@@ -0,0 +1,13 @@
+"use client";
+
+import {
+  ThemeProvider,
+  type ThemeProviderProps,
+} from "next-themes";
+
+export function AppThemeProvider({
+  children,
+  ...props
+}: ThemeProviderProps) {
+  return <ThemeProvider {...props}>{children}</ThemeProvider>;
+}
diff --git a/components/assessment/AssessmentApp.tsx b/components/assessment/AssessmentApp.tsx
index 42a21cf..4a46633 100644
--- a/components/assessment/AssessmentApp.tsx
+++ b/components/assessment/AssessmentApp.tsx
@@ -1,6 +1,5 @@
 "use client";
 
-import Link from "next/link";
 import { useEffect, useState } from "react";
 import { Pizza } from "@components/pizza/Pizza";
 import { useAssessment } from "@hooks/useAssessment";
@@ -113,16 +112,12 @@ export function AssessmentApp({ initialShareCode }: AssessmentAppProps) {
   return (
     <Shell>
       <TopBar>
-        <Link href="/" passHref legacyBehavior>
-          <BrandLink>
-            Validator <BrandAccent>Beat</BrandAccent>
-          </BrandLink>
-        </Link>
+        <BrandLink href="/">
+          Validator <BrandAccent>Beat</BrandAccent>
+        </BrandLink>
         <TagPill>v0.1 · self-assessment</TagPill>
         <TopSpacer />
-        <Link href="/methodology/" passHref legacyBehavior>
-          <TopNavLink>Methodology</TopNavLink>
-        </Link>
+        <TopNavLink href="/methodology/">Methodology</TopNavLink>
         <ThemeToggle />
       </TopBar>
 
diff --git a/components/assessment/ThemeToggle.tsx b/components/assessment/ThemeToggle.tsx
index 7582ed5..4124c74 100644
--- a/components/assessment/ThemeToggle.tsx
+++ b/components/assessment/ThemeToggle.tsx
@@ -1,4 +1,5 @@
-import { useTheme } from "@hooks/useTheme";
+import { useEffect, useState } from "react";
+import { useTheme } from "next-themes";
 import { ThemeToggleButton } from "./stitches";
 
 const SunIcon = () => (
@@ -28,13 +29,17 @@ const MoonIcon = () => (
  * until mounted so it never mismatches the server-rendered markup.
  */
 export function ThemeToggle() {
-  const { theme, toggle, mounted } = useTheme();
-  const isDark = theme === "dark";
+  const { resolvedTheme, setTheme } = useTheme();
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => setMounted(true), []);
+
+  const isDark = mounted && resolvedTheme === "dark";
 
   return (
     <ThemeToggleButton
       type="button"
-      onClick={toggle}
+      onClick={() => setTheme(isDark ? "light" : "dark")}
       aria-label={isDark ? "Switch to light mode" : "Switch to dark mode"}
       title={isDark ? "Switch to light mode" : "Switch to dark mode"}
     >
diff --git a/components/assessment/stitches.ts b/components/assessment/stitches.ts
index fd43d70..79c55e4 100644
--- a/components/assessment/stitches.ts
+++ b/components/assessment/stitches.ts
@@ -1,5 +1,6 @@
 import { Box, Text, styled } from "@obolnetwork/obol-ui";
 import type { SliceColor } from "@lib/rubric/types";
+import NextLink from "next/link";
 
 /** Validator Beat risk palette — maps to theme-tokens.css */
 export const risk = {
@@ -46,7 +47,7 @@ export const TopBar = styled(Box, {
   flexShrink: 0,
 });
 
-export const BrandLink = styled("a", {
+export const BrandLink = styled(NextLink, {
   fontSize: "$3",
   fontWeight: "$bold",
   letterSpacing: "-0.01em",
@@ -70,7 +71,7 @@ export const TagPill = styled(Box, {
 
 export const TopSpacer = styled(Box, { marginLeft: "auto" });
 
-export const TopNavLink = styled("a", {
+export const TopNavLink = styled(NextLink, {
   fontSize: "$2",
   fontWeight: "$medium",
   color: "$textMiddle",
diff --git a/components/layout/Navbar.tsx b/components/layout/Navbar.tsx
index ccf1ead..a8b52f7 100644
--- a/components/layout/Navbar.tsx
+++ b/components/layout/Navbar.tsx
@@ -1,4 +1,4 @@
-import { Box, Link, Text } from "@obolnetwork/obol-ui";
+import { Box, Text } from "@obolnetwork/obol-ui";
 import NextLink from "next/link";
 import { useRouter } from "next/router";
 import { SITE_NAME } from "@constants/index";
@@ -25,13 +25,11 @@ export function Navbar() {
         backgroundColor: "$bg01",
       }}
     >
-      <NextLink href="/" passHref legacyBehavior>
-        <Link css={{ textDecoration: "none" }}>
-          <Text variant="h4" css={{ color: "$body", fontWeight: "$semibold" }}>
-            {SITE_NAME}
-          </Text>
-        </Link>
-      </NextLink>
+      <Box as={NextLink} href="/" css={{ textDecoration: "none" }}>
+        <Text variant="h4" css={{ color: "$body", fontWeight: "$semibold" }}>
+          {SITE_NAME}
+        </Text>
+      </Box>
       <Box as="nav" css={{ display: "flex", gap: "$lg" }}>
         {NAV_ITEMS.map(({ href, label }) => {
           const active =
@@ -39,18 +37,19 @@ export function Navbar() {
               ? router.pathname === "/"
               : router.pathname.startsWith(href.replace(/\/$/, ""));
           return (
-            <NextLink key={href} href={href} passHref legacyBehavior>
-              <Link
-                css={{
-                  color: active ? "var(--theme-brand)" : "$body",
-                  fontWeight: active ? "$semibold" : "$normal",
-                  textDecoration: "none",
-                  "&:hover": { color: "var(--theme-brand)" },
-                }}
-              >
-                {label}
-              </Link>
-            </NextLink>
+            <Box
+              as={NextLink}
+              key={href}
+              href={href}
+              css={{
+                color: active ? "var(--theme-brand)" : "$body",
+                fontWeight: active ? "$semibold" : "$normal",
+                textDecoration: "none",
+                "&:hover": { color: "var(--theme-brand)" },
+              }}
+            >
+              {label}
+            </Box>
           );
         })}
       </Box>
diff --git a/components/pizza/Pizza.tsx b/components/pizza/Pizza.tsx
index a4f701b..14c963e 100644
--- a/components/pizza/Pizza.tsx
+++ b/components/pizza/Pizza.tsx
@@ -197,8 +197,8 @@ export function Pizza({
             )}
             {showLabels && (
               <text
-                x={lx}
-                y={ly}
+                x={+lx.toFixed(2)}
+                y={+ly.toFixed(2)}
                 className="vbpizza__lbl"
                 textAnchor="middle"
                 dominantBaseline="middle"
diff --git a/hooks/useTheme.ts b/hooks/useTheme.ts
deleted file mode 100644
index 5cc7184..0000000
--- a/hooks/useTheme.ts
+++ /dev/null
@@ -1,58 +0,0 @@
-import { useEffect, useState } from "react";
-
-export type Theme = "light" | "dark";
-
-const STORAGE_KEY = "vb-theme";
-
-function applyTheme(theme: Theme) {
-  const root = document.documentElement;
-  if (theme === "dark") {
-    root.setAttribute("data-theme", "dark");
-  } else {
-    root.removeAttribute("data-theme");
-  }
-}
-
-/**
- * Light/dark theme state, persisted to localStorage and reflected as
- * data-theme on <html>. Defaults to light. The pre-paint script in
- * _document.tsx sets the attribute before hydration to avoid a flash;
- * this hook syncs React state to it on mount.
- */
-export function useTheme() {
-  // Match the server-rendered markup (light) on first client render, then
-  // reconcile to the persisted choice in the effect below — no hydration gap.
-  const [theme, setTheme] = useState<Theme>("light");
-  const [mounted, setMounted] = useState(false);
-
-  useEffect(() => {
-    let stored: Theme | null = null;
-    try {
-      stored = localStorage.getItem(STORAGE_KEY) as Theme | null;
-    } catch {
-      stored = null;
-    }
-    const current =
-      stored ??
-      (document.documentElement.getAttribute("data-theme") === "dark"
-        ? "dark"
-        : "light");
-    setTheme(current);
-    setMounted(true);
-  }, []);
-
-  const toggle = () => {
-    setTheme((prev) => {
-      const next: Theme = prev === "dark" ? "light" : "dark";
-      applyTheme(next);
-      try {
-        localStorage.setItem(STORAGE_KEY, next);
-      } catch {
-        /* private mode / storage disabled — theme still applies for the session */
-      }
-      return next;
-    });
-  };
-
-  return { theme, toggle, mounted };
-}
diff --git a/package.json b/package.json
index 696331e..88bb8d3 100644
--- a/package.json
+++ b/package.json
@@ -26,6 +26,7 @@
     "@stitches/react": "1.2.8",
     "html-to-image": "1.11.13",
     "next": "15.5.15",
+    "next-themes": "^0.4.6",
     "react": "19.2.3",
     "react-dom": "19.2.3",
     "react-is": "19.2.3"
diff --git a/pages/_app.tsx b/pages/_app.tsx
index 6f6d6e8..7dc44e8 100644
--- a/pages/_app.tsx
+++ b/pages/_app.tsx
@@ -1,3 +1,4 @@
+import { AppThemeProvider } from "@components/AppThemeProvider";
 import { globalCss, Provider as TooltipProvider } from "@obolnetwork/obol-ui";
 import "@styles/colors_and_type.css";
 import "@styles/obol-bridge.css";
@@ -48,8 +49,14 @@ export default function App({ Component, pageProps }: AppProps) {
       : undefined;
 
   return (
-    <TooltipProvider>
-      <Head>
+    <AppThemeProvider
+      attribute="data-theme"
+      defaultTheme="light"
+      storageKey="vb-theme"
+      enableSystem={false}
+    >
+      <TooltipProvider>
+        <Head>
         <title>{title}</title>
         <meta name="description" content={description} />
         <meta property="og:title" content={title} />
@@ -65,8 +72,9 @@ export default function App({ Component, pageProps }: AppProps) {
             <meta name="twitter:image" content={ogImage} />
           </>
         )}
-      </Head>
-      <Component {...pageProps} />
-    </TooltipProvider>
+        </Head>
+        <Component {...pageProps} />
+      </TooltipProvider>
+    </AppThemeProvider>
   );
 }
diff --git a/pages/_document.tsx b/pages/_document.tsx
index aa12d6b..69c98f5 100644
--- a/pages/_document.tsx
+++ b/pages/_document.tsx
@@ -13,14 +13,8 @@ const BASE_PATH = process.env.NEXT_PUBLIC_BASE_PATH ?? "";
 
 export default function Document() {
   return (
-    <Html lang="en">
+    <Html lang="en" suppressHydrationWarning>
       <Head>
-        <script
-          dangerouslySetInnerHTML={{
-            __html:
-              "(function(){try{if(localStorage.getItem('vb-theme')==='dark')document.documentElement.setAttribute('data-theme','dark');}catch(e){}})();",
-          }}
-        />
         <style id="obol" dangerouslySetInnerHTML={{ __html: getCssText() }} />
         <link rel="icon" type="image/svg+xml" href={`${BASE_PATH}/icon.svg`} />
         <link rel="icon" type="image/png" sizes="32x32" href={`${BASE_PATH}/favicon-32.png`} />
diff --git a/pages/methodology.tsx b/pages/methodology.tsx
index 20398a7..39de130 100644
--- a/pages/methodology.tsx
+++ b/pages/methodology.tsx
@@ -14,11 +14,9 @@ export default function MethodologyPage() {
   return (
     <div className="vb-methodology">
       <TopBar as="header" className="vb-methodology__top">
-        <Link href="/" passHref legacyBehavior>
-          <BrandLink>
-            Validator <BrandAccent>Beat</BrandAccent>
-          </BrandLink>
-        </Link>
+        <BrandLink href="/">
+          Validator <BrandAccent>Beat</BrandAccent>
+        </BrandLink>
         <TagPill>v0.1 · methodology</TagPill>
         <TopSpacer />
         <ThemeToggle />
diff --git a/styles/theme-tokens.css b/styles/theme-tokens.css
index 1b2974a..8ed606e 100644
--- a/styles/theme-tokens.css
+++ b/styles/theme-tokens.css
@@ -52,7 +52,7 @@
 
 /* =============================================================================
    DARK THEME — Obol-branded dark palette, mirrors the standalone prototype.
-   Activated by data-theme="dark" on <html> (see hooks/useTheme + _document).
+   Activated by data-theme="dark" on <html> (see next-themes ThemeProvider in _app).
    Overrides the --theme-* source values; the alias layer below recomputes
    automatically. --bg-01..05 are re-pointed past obol-ui's --colors-* tokens.
    ============================================================================= */
diff --git a/yarn.lock b/yarn.lock
index b1dfd90..cbe8fd0 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -4669,6 +4669,11 @@ neo-async@^2.6.2:
   resolved "https://registry.yarnpkg.com/neo-async/-/neo-async-2.6.2.tgz#b4aafb93e3aeb2d8174ca53cf163ab7d7308305f"
   integrity sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==
 
+next-themes@^0.4.6:
+  version "0.4.6"
+  resolved "https://registry.yarnpkg.com/next-themes/-/next-themes-0.4.6.tgz#8d7e92d03b8fea6582892a50a928c9b23502e8b6"
+  integrity sha512-pZvgD5L0IEvX5/9GWyHMf3m8BKiVQwsCMHfoFosXtXBMnaS0ZnIJ9ST4b4NqLVKDEm8QBxoNNGNaBv2JNF6XNA==
+
 next@14.2.35:
   version "14.2.35"
   resolved "https://registry.yarnpkg.com/next/-/next-14.2.35.tgz#7c68873a15fe5a19401f2f993fea535be3366ee9"