From b50cfd7552f840126281d6a7bf180d963fca7feb Mon Sep 17 00:00:00 2001
From: Sharanya Nagar <sharanyanagar@yahoo.in>
Date: Thu, 13 Aug 2026 08:30:30 +0530
Subject: [PATCH 01/19] feat: add light theme token set, prefers-color-scheme
 support, and explicit theme toggle

---
 frontend/app/globals.css                   | 125 +++++++++++++++++--
 frontend/app/layout.tsx                    |   9 +-
 frontend/components/layout/Navbar.tsx      |   2 +
 frontend/components/layout/ThemeToggle.tsx | 133 +++++++++++++++++++++
 4 files changed, 258 insertions(+), 11 deletions(-)
 create mode 100644 frontend/components/layout/ThemeToggle.tsx

diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index 14449ed..ded1bc0 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -3,7 +3,7 @@
 /* ═══════════════════════════════════════════════════════════════════════════
    Tinted design system
 
-   Why a near-neutral dark canvas:
+   Why near-neutral canvases:
    this app's entire job is to show colour accurately. A tinted background
    shifts perceived skin tone — a warm page makes every swatch read warmer, and
    the undertone call is the product. So the surfaces are deliberately close to
@@ -11,11 +11,20 @@
    saturated colour on screen belongs to the shades and the product photos.
 
    Every text/surface pair below is verified at WCAG AA (4.5:1) for body text.
-   Measured against --color-bg / --color-surface / --color-raised respectively:
+
+   Dark theme (default / data-theme="dark"):
+   Measured against --color-bg (#0b0b0c) / --color-surface (#141416) / --color-raised (#1c1c1f):
      text        17.90 / 16.74 / 15.47
      text-soft    9.20 /  8.60 /  7.95
      text-muted   5.49 /  5.13 /  4.74
      accent       6.45 /  6.04 /  5.58
+
+   Light theme (prefers-color-scheme: light / data-theme="light"):
+   Measured against --color-bg (#f7f8f9) / --color-surface (#ffffff) / --color-raised (#e8eaea):
+     text        17.15 / 18.23 / 15.24
+     text-soft    8.29 /  8.82 /  7.37
+     text-muted   5.49 /  5.83 /  4.88
+     accent       6.10 /  6.49 /  5.43
    If you change a value here, re-check it before committing.
    ═══════════════════════════════════════════════════════════════════════════ */
 
@@ -75,7 +84,6 @@
   --radius-pill: 999px;
 
   /* ── Elevation ────────────────────────────────────────────────────────── */
-  /* Dark UIs get depth from a light top edge, not from a heavier drop shadow. */
   --shadow-card: 0 1px 0 0 rgba(255, 255, 255, 0.05) inset,
                  0 12px 32px -16px rgba(0, 0, 0, 0.9);
   --shadow-lift: 0 1px 0 0 rgba(255, 255, 255, 0.07) inset,
@@ -90,6 +98,103 @@
   --duration-slow: 520ms;
 }
 
+/* ═══════════════════════════════════════════════════════════════════════════
+   Theme Token Rules
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+:root,
+html[data-theme="dark"] {
+  color-scheme: dark;
+  --color-bg: #0b0b0c;
+  --color-surface: #141416;
+  --color-raised: #1c1c1f;
+  --color-overlay: rgba(6, 6, 7, 0.72);
+
+  --color-text: #f5f4f2;
+  --color-text-soft: #b4b1ab;
+  --color-text-muted: #8a8780;
+
+  --color-accent: #c68642;
+  --color-accent-bright: #e0a063;
+  --color-accent-dim: rgba(198, 134, 66, 0.14);
+
+  --color-success: #6fbf8b;
+  --color-warn: #e8b04b;
+  --color-danger: #f0796b;
+
+  --color-line: rgba(255, 255, 255, 0.09);
+  --color-line-strong: rgba(255, 255, 255, 0.16);
+
+  --shadow-card: 0 1px 0 0 rgba(255, 255, 255, 0.05) inset,
+                 0 12px 32px -16px rgba(0, 0, 0, 0.9);
+  --shadow-lift: 0 1px 0 0 rgba(255, 255, 255, 0.07) inset,
+                 0 24px 48px -20px rgba(0, 0, 0, 0.95);
+  --shadow-glow: 0 0 0 1px rgba(198, 134, 66, 0.35),
+                 0 16px 40px -20px rgba(198, 134, 66, 0.45);
+}
+
+@media (prefers-color-scheme: light) {
+  :root:not([data-theme="dark"]) {
+    color-scheme: light;
+    --color-bg: #f7f8f9;
+    --color-surface: #ffffff;
+    --color-raised: #e8eaea;
+    --color-overlay: rgba(247, 248, 249, 0.80);
+
+    --color-text: #141517;
+    --color-text-soft: #484a4e;
+    --color-text-muted: #616368;
+
+    --color-accent: #875018;
+    --color-accent-bright: #6e3e0e;
+    --color-accent-dim: rgba(135, 80, 24, 0.12);
+
+    --color-success: #2b7a4b;
+    --color-warn: #a36209;
+    --color-danger: #cf3b2b;
+
+    --color-line: rgba(0, 0, 0, 0.08);
+    --color-line-strong: rgba(0, 0, 0, 0.16);
+
+    --shadow-card: 0 1px 3px 0 rgba(0, 0, 0, 0.06),
+                   0 4px 12px -2px rgba(0, 0, 0, 0.08);
+    --shadow-lift: 0 4px 16px -2px rgba(0, 0, 0, 0.10),
+                   0 12px 28px -6px rgba(0, 0, 0, 0.12);
+    --shadow-glow: 0 0 0 1px rgba(135, 80, 24, 0.30),
+                   0 8px 24px -6px rgba(135, 80, 24, 0.25);
+  }
+}
+
+html[data-theme="light"] {
+  color-scheme: light;
+  --color-bg: #f7f8f9;
+  --color-surface: #ffffff;
+  --color-raised: #e8eaea;
+  --color-overlay: rgba(247, 248, 249, 0.80);
+
+  --color-text: #141517;
+  --color-text-soft: #484a4e;
+  --color-text-muted: #616368;
+
+  --color-accent: #875018;
+  --color-accent-bright: #6e3e0e;
+  --color-accent-dim: rgba(135, 80, 24, 0.12);
+
+  --color-success: #2b7a4b;
+  --color-warn: #a36209;
+  --color-danger: #cf3b2b;
+
+  --color-line: rgba(0, 0, 0, 0.08);
+  --color-line-strong: rgba(0, 0, 0, 0.16);
+
+  --shadow-card: 0 1px 3px 0 rgba(0, 0, 0, 0.06),
+                 0 4px 12px -2px rgba(0, 0, 0, 0.08);
+  --shadow-lift: 0 4px 16px -2px rgba(0, 0, 0, 0.10),
+                 0 12px 28px -6px rgba(0, 0, 0, 0.12);
+  --shadow-glow: 0 0 0 1px rgba(135, 80, 24, 0.30),
+                 0 8px 24px -6px rgba(135, 80, 24, 0.25);
+}
+
 /* ═══════════════════════════════════════════════════════════════════════════
    Base
    ═══════════════════════════════════════════════════════════════════════════ */
@@ -113,18 +218,18 @@ body {
 }
 
 ::selection {
-  background: rgba(198, 134, 66, 0.3);
+  background: var(--color-accent-dim);
   color: var(--color-text);
 }
 
 ::-webkit-scrollbar { width: 10px; height: 10px; }
 ::-webkit-scrollbar-track { background: transparent; }
 ::-webkit-scrollbar-thumb {
-  background: rgba(255, 255, 255, 0.12);
+  background: var(--color-line-strong);
   border: 3px solid var(--color-bg);
   border-radius: 999px;
 }
-::-webkit-scrollbar-thumb:hover { background: rgba(255, 255, 255, 0.22); }
+::-webkit-scrollbar-thumb:hover { background: var(--color-text-muted); }
 
 /* ═══════════════════════════════════════════════════════════════════════════
    Utilities
@@ -157,10 +262,10 @@ body {
    vanish into the page. */
 .bg-swatch-check {
   background-image:
-    linear-gradient(45deg, rgba(255,255,255,0.04) 25%, transparent 25%),
-    linear-gradient(-45deg, rgba(255,255,255,0.04) 25%, transparent 25%),
-    linear-gradient(45deg, transparent 75%, rgba(255,255,255,0.04) 75%),
-    linear-gradient(-45deg, transparent 75%, rgba(255,255,255,0.04) 75%);
+    linear-gradient(45deg, var(--color-line-strong) 25%, transparent 25%),
+    linear-gradient(-45deg, var(--color-line-strong) 25%, transparent 25%),
+    linear-gradient(45deg, transparent 75%, var(--color-line-strong) 75%),
+    linear-gradient(-45deg, transparent 75%, var(--color-line-strong) 75%);
   background-size: 12px 12px;
   background-position: 0 0, 0 6px, 6px -6px, -6px 0;
 }
diff --git a/frontend/app/layout.tsx b/frontend/app/layout.tsx
index 1f9e796..cdf556f 100644
--- a/frontend/app/layout.tsx
+++ b/frontend/app/layout.tsx
@@ -34,7 +34,14 @@ export default function RootLayout({
   children: React.ReactNode;
 }) {
   return (
-    <html lang="en" className={`${inter.variable} ${fraunces.variable}`}>
+    <html lang="en" className={`${inter.variable} ${fraunces.variable}`} suppressHydrationWarning>
+      <head>
+        <script
+          dangerouslySetInnerHTML={{
+            __html: `(function(){try{var t=localStorage.getItem("tinted-theme");if(t==="light"||t==="dark"){document.documentElement.setAttribute("data-theme",t);}}catch(e){}})();`,
+          }}
+        />
+      </head>
       <body className="min-h-screen bg-bg text-text antialiased">
         {/* First thing in the tab order — keyboard users shouldn't have to
             traverse the nav on every page. */}
diff --git a/frontend/components/layout/Navbar.tsx b/frontend/components/layout/Navbar.tsx
index 7d77b0b..c7da2a2 100644
--- a/frontend/components/layout/Navbar.tsx
+++ b/frontend/components/layout/Navbar.tsx
@@ -4,6 +4,7 @@ import Link from "next/link";
 import { usePathname } from "next/navigation";
 import { cn } from "@/lib/utils";
 import { AuthButton } from "@/components/layout/AuthButton";
+import { ThemeToggle } from "@/components/layout/ThemeToggle";
 
 const LINKS = [
   { href: "/", label: "Shade match" },
@@ -62,6 +63,7 @@ export function Navbar({ className }: { className?: string }) {
         </ul>
 
         <div className="ml-auto flex items-center gap-3">
+          <ThemeToggle />
           <AuthButton />
         </div>
       </nav>
diff --git a/frontend/components/layout/ThemeToggle.tsx b/frontend/components/layout/ThemeToggle.tsx
new file mode 100644
index 0000000..49f5770
--- /dev/null
+++ b/frontend/components/layout/ThemeToggle.tsx
@@ -0,0 +1,133 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { cn } from "@/lib/utils";
+
+type ThemeMode = "system" | "light" | "dark";
+
+export function ThemeToggle({ className }: { className?: string }) {
+  const [theme, setTheme] = useState<ThemeMode>("system");
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+    const stored = localStorage.getItem("tinted-theme") as ThemeMode | null;
+    if (stored === "light" || stored === "dark" || stored === "system") {
+      setTheme(stored);
+    }
+  }, []);
+
+  const updateTheme = (nextTheme: ThemeMode) => {
+    setTheme(nextTheme);
+    localStorage.setItem("tinted-theme", nextTheme);
+
+    const root = document.documentElement;
+    if (nextTheme === "system") {
+      root.removeAttribute("data-theme");
+    } else {
+      root.setAttribute("data-theme", nextTheme);
+    }
+
+    // Update meta theme-color tag dynamically
+    const metaThemeColor = document.querySelector('meta[name="theme-color"]');
+    if (metaThemeColor) {
+      const isLight =
+        nextTheme === "light" ||
+        (nextTheme === "system" &&
+          window.matchMedia("(prefers-color-scheme: light)").matches);
+      metaThemeColor.setAttribute("content", isLight ? "#f7f8f9" : "#0b0b0c");
+    }
+  };
+
+  const cycleTheme = () => {
+    if (theme === "system") updateTheme("light");
+    else if (theme === "light") updateTheme("dark");
+    else updateTheme("system");
+  };
+
+  if (!mounted) {
+    return (
+      <div
+        className={cn(
+          "inline-flex h-9 w-9 items-center justify-center rounded-pill border border-line bg-raised/50",
+          className,
+        )}
+        aria-hidden="true"
+      />
+    );
+  }
+
+  const label =
+    theme === "system"
+      ? "Theme: System (click to switch to Light)"
+      : theme === "light"
+      ? "Theme: Light (click to switch to Dark)"
+      : "Theme: Dark (click to switch to System)";
+
+  return (
+    <button
+      type="button"
+      onClick={cycleTheme}
+      aria-label={label}
+      title={label}
+      className={cn(
+        "inline-flex h-9 items-center gap-1.5 rounded-pill border border-line bg-raised/60 px-2.5 py-1",
+        "text-small font-medium text-text-soft transition-colors duration-[--duration-fast]",
+        "hover:bg-raised hover:text-text focus-visible:outline-2",
+        className,
+      )}
+    >
+      {theme === "light" && (
+        <>
+          <svg
+            className="h-4 w-4 text-accent"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+            strokeWidth={2}
+            aria-hidden="true"
+          >
+            <circle cx="12" cy="12" r="4" />
+            <path strokeLinecap="round" d="M12 2v2m0 16v2M4.93 4.93l1.41 1.41m11.32 11.32l1.41 1.41M2 12h2m16 0h2M6.34 17.66l-1.41 1.41M19.07 4.93l-1.41 1.41" />
+          </svg>
+          <span className="hidden sm:inline text-xs">Light</span>
+        </>
+      )}
+      {theme === "dark" && (
+        <>
+          <svg
+            className="h-4 w-4 text-accent"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+            strokeWidth={2}
+            aria-hidden="true"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              d="M20.354 15.354A9 9 0 018.646 3.646 9.003 9.003 0 0012 21a9.003 9.003 0 008.354-5.646z"
+            />
+          </svg>
+          <span className="hidden sm:inline text-xs">Dark</span>
+        </>
+      )}
+      {theme === "system" && (
+        <>
+          <svg
+            className="h-4 w-4 text-text-muted"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+            strokeWidth={2}
+            aria-hidden="true"
+          >
+            <rect x="3" y="4" width="18" height="12" rx="2" />
+            <path strokeLinecap="round" d="M8 20h8m-4-4v4" />
+          </svg>
+          <span className="hidden sm:inline text-xs">Auto</span>
+        </>
+      )}
+    </button>
+  );
+}

From 00ef8c30d6777232ee1eaeee22f419764cbb25cd Mon Sep 17 00:00:00 2001
From: Sharanya Nagar <sharanyanagar@yahoo.in>
Date: Thu, 13 Aug 2026 08:41:35 +0530
Subject: [PATCH 02/19] refactor: address code review feedback for light theme
 and ThemeToggle

---
 frontend/app/globals.css                   | 136 ++++++++++++---------
 frontend/app/layout.tsx                    |   5 +-
 frontend/components/layout/ThemeToggle.tsx |  21 +++-
 3 files changed, 103 insertions(+), 59 deletions(-)

diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index ded1bc0..70cd6d8 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -102,6 +102,36 @@
    Theme Token Rules
    ═══════════════════════════════════════════════════════════════════════════ */
 
+:root {
+  /* ── Shared Light Theme Token Definitions (Single Source of Truth) ────── */
+  --light-color-bg: #f7f8f9;
+  --light-color-surface: #ffffff;
+  --light-color-raised: #e8eaea;
+  --light-color-overlay: rgba(247, 248, 249, 0.80);
+
+  --light-color-text: #141517;
+  --light-color-text-soft: #484a4e;
+  --light-color-text-muted: #616368;
+
+  --light-color-accent: #875018;
+  --light-color-accent-bright: #6e3e0e;
+  --light-color-accent-dim: rgba(135, 80, 24, 0.12);
+
+  --light-color-success: #2b7a4b;
+  --light-color-warn: #a36209;
+  --light-color-danger: #cf3b2b;
+
+  --light-color-line: rgba(0, 0, 0, 0.08);
+  --light-color-line-strong: rgba(0, 0, 0, 0.16);
+
+  --light-shadow-card: 0 1px 3px 0 rgba(0, 0, 0, 0.06),
+                       0 4px 12px -2px rgba(0, 0, 0, 0.08);
+  --light-shadow-lift: 0 4px 16px -2px rgba(0, 0, 0, 0.10),
+                       0 12px 28px -6px rgba(0, 0, 0, 0.12);
+  --light-shadow-glow: 0 0 0 1px rgba(135, 80, 24, 0.30),
+                       0 8px 24px -6px rgba(135, 80, 24, 0.25);
+}
+
 :root,
 html[data-theme="dark"] {
   color-scheme: dark;
@@ -133,66 +163,60 @@ html[data-theme="dark"] {
                  0 16px 40px -20px rgba(198, 134, 66, 0.45);
 }
 
+html[data-theme="light"] {
+  color-scheme: light;
+  --color-bg: var(--light-color-bg);
+  --color-surface: var(--light-color-surface);
+  --color-raised: var(--light-color-raised);
+  --color-overlay: var(--light-color-overlay);
+
+  --color-text: var(--light-color-text);
+  --color-text-soft: var(--light-color-text-soft);
+  --color-text-muted: var(--light-color-text-muted);
+
+  --color-accent: var(--light-color-accent);
+  --color-accent-bright: var(--light-color-accent-bright);
+  --color-accent-dim: var(--light-color-accent-dim);
+
+  --color-success: var(--light-color-success);
+  --color-warn: var(--light-color-warn);
+  --color-danger: var(--light-color-danger);
+
+  --color-line: var(--light-color-line);
+  --color-line-strong: var(--light-color-line-strong);
+
+  --shadow-card: var(--light-shadow-card);
+  --shadow-lift: var(--light-shadow-lift);
+  --shadow-glow: var(--light-shadow-glow);
+}
+
 @media (prefers-color-scheme: light) {
   :root:not([data-theme="dark"]) {
     color-scheme: light;
-    --color-bg: #f7f8f9;
-    --color-surface: #ffffff;
-    --color-raised: #e8eaea;
-    --color-overlay: rgba(247, 248, 249, 0.80);
-
-    --color-text: #141517;
-    --color-text-soft: #484a4e;
-    --color-text-muted: #616368;
-
-    --color-accent: #875018;
-    --color-accent-bright: #6e3e0e;
-    --color-accent-dim: rgba(135, 80, 24, 0.12);
-
-    --color-success: #2b7a4b;
-    --color-warn: #a36209;
-    --color-danger: #cf3b2b;
-
-    --color-line: rgba(0, 0, 0, 0.08);
-    --color-line-strong: rgba(0, 0, 0, 0.16);
-
-    --shadow-card: 0 1px 3px 0 rgba(0, 0, 0, 0.06),
-                   0 4px 12px -2px rgba(0, 0, 0, 0.08);
-    --shadow-lift: 0 4px 16px -2px rgba(0, 0, 0, 0.10),
-                   0 12px 28px -6px rgba(0, 0, 0, 0.12);
-    --shadow-glow: 0 0 0 1px rgba(135, 80, 24, 0.30),
-                   0 8px 24px -6px rgba(135, 80, 24, 0.25);
-  }
-}
+    --color-bg: var(--light-color-bg);
+    --color-surface: var(--light-color-surface);
+    --color-raised: var(--light-color-raised);
+    --color-overlay: var(--light-color-overlay);
 
-html[data-theme="light"] {
-  color-scheme: light;
-  --color-bg: #f7f8f9;
-  --color-surface: #ffffff;
-  --color-raised: #e8eaea;
-  --color-overlay: rgba(247, 248, 249, 0.80);
-
-  --color-text: #141517;
-  --color-text-soft: #484a4e;
-  --color-text-muted: #616368;
-
-  --color-accent: #875018;
-  --color-accent-bright: #6e3e0e;
-  --color-accent-dim: rgba(135, 80, 24, 0.12);
-
-  --color-success: #2b7a4b;
-  --color-warn: #a36209;
-  --color-danger: #cf3b2b;
-
-  --color-line: rgba(0, 0, 0, 0.08);
-  --color-line-strong: rgba(0, 0, 0, 0.16);
-
-  --shadow-card: 0 1px 3px 0 rgba(0, 0, 0, 0.06),
-                 0 4px 12px -2px rgba(0, 0, 0, 0.08);
-  --shadow-lift: 0 4px 16px -2px rgba(0, 0, 0, 0.10),
-                 0 12px 28px -6px rgba(0, 0, 0, 0.12);
-  --shadow-glow: 0 0 0 1px rgba(135, 80, 24, 0.30),
-                 0 8px 24px -6px rgba(135, 80, 24, 0.25);
+    --color-text: var(--light-color-text);
+    --color-text-soft: var(--light-color-text-soft);
+    --color-text-muted: var(--light-color-text-muted);
+
+    --color-accent: var(--light-color-accent);
+    --color-accent-bright: var(--light-color-accent-bright);
+    --color-accent-dim: var(--light-color-accent-dim);
+
+    --color-success: var(--light-color-success);
+    --color-warn: var(--light-color-warn);
+    --color-danger: var(--light-color-danger);
+
+    --color-line: var(--light-color-line);
+    --color-line-strong: var(--light-color-line-strong);
+
+    --shadow-card: var(--light-shadow-card);
+    --shadow-lift: var(--light-shadow-lift);
+    --shadow-glow: var(--light-shadow-glow);
+  }
 }
 
 /* ═══════════════════════════════════════════════════════════════════════════
diff --git a/frontend/app/layout.tsx b/frontend/app/layout.tsx
index cdf556f..d75b7a4 100644
--- a/frontend/app/layout.tsx
+++ b/frontend/app/layout.tsx
@@ -1,5 +1,6 @@
 import type { Metadata, Viewport } from "next";
 import { Inter, Fraunces } from "next/font/google";
+import Script from "next/script";
 import { Navbar } from "@/components/layout/Navbar";
 import "./globals.css";
 
@@ -36,7 +37,9 @@ export default function RootLayout({
   return (
     <html lang="en" className={`${inter.variable} ${fraunces.variable}`} suppressHydrationWarning>
       <head>
-        <script
+        <Script
+          id="theme-preload"
+          strategy="beforeInteractive"
           dangerouslySetInnerHTML={{
             __html: `(function(){try{var t=localStorage.getItem("tinted-theme");if(t==="light"||t==="dark"){document.documentElement.setAttribute("data-theme",t);}}catch(e){}})();`,
           }}
diff --git a/frontend/components/layout/ThemeToggle.tsx b/frontend/components/layout/ThemeToggle.tsx
index 49f5770..cbf2c76 100644
--- a/frontend/components/layout/ThemeToggle.tsx
+++ b/frontend/components/layout/ThemeToggle.tsx
@@ -17,6 +17,20 @@ export function ThemeToggle({ className }: { className?: string }) {
     }
   }, []);
 
+  // Listen for system preference changes when in 'system' mode
+  useEffect(() => {
+    if (theme !== "system") return;
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: light)");
+    const handleChange = (e: MediaQueryListEvent) => {
+      const metaThemeColor = document.querySelector('meta[name="theme-color"]');
+      if (metaThemeColor) {
+        metaThemeColor.setAttribute("content", e.matches ? "#f7f8f9" : "#0b0b0c");
+      }
+    };
+    mediaQuery.addEventListener("change", handleChange);
+    return () => mediaQuery.removeEventListener("change", handleChange);
+  }, [theme]);
+
   const updateTheme = (nextTheme: ThemeMode) => {
     setTheme(nextTheme);
     localStorage.setItem("tinted-theme", nextTheme);
@@ -49,11 +63,14 @@ export function ThemeToggle({ className }: { className?: string }) {
     return (
       <div
         className={cn(
-          "inline-flex h-9 w-9 items-center justify-center rounded-pill border border-line bg-raised/50",
+          "inline-flex h-9 items-center gap-1.5 rounded-pill border border-line bg-raised/50 px-2.5 py-1",
           className,
         )}
         aria-hidden="true"
-      />
+      >
+        <div className="h-4 w-4 rounded-full bg-text-muted/20" />
+        <div className="hidden sm:inline-block h-3 w-8 rounded bg-text-muted/20" />
+      </div>
     );
   }
 

From 5cf6233d19f1f33ba6c1f67f99e1ed93ecf05bda Mon Sep 17 00:00:00 2001
From: Sharanya Nagar <sharanyanagar@yahoo.in>
Date: Thu, 13 Aug 2026 08:49:31 +0530
Subject: [PATCH 03/19] merge conflict solved

---
 frontend/app/globals.css | 108 ++++++++++++++++++++++++++++++++++-----
 1 file changed, 96 insertions(+), 12 deletions(-)

diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index 70cd6d8..29c0352 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -10,6 +10,9 @@
    neutral grey (a hint cool, to counter the warmth of the accent), and the only
    saturated colour on screen belongs to the shades and the product photos.
 
+   The colour-accuracy argument still holds: shades and product photos are shown
+   on plain white (--color-swatch-ground) so nothing tints the judgement.
+
    Every text/surface pair below is verified at WCAG AA (4.5:1) for body text.
 
    Dark theme (default / data-theme="dark"):
@@ -34,6 +37,7 @@
   --color-surface: #141416;
   --color-raised: #1c1c1f;
   --color-overlay: rgba(6, 6, 7, 0.72);
+  --color-swatch-ground: #ffffff;
 
   /* ── Text ─────────────────────────────────────────────────────────────── */
   --color-text: #f5f4f2;
@@ -41,11 +45,12 @@
   --color-text-muted: #8a8780;
 
   /* ── Accent ───────────────────────────────────────────────────────────── */
-  /* Bronze rather than pink: it sits beside every skin tone without competing
-     with it, which a saturated pink does not. */
   --color-accent: #c68642;
   --color-accent-bright: #e0a063;
+  --color-accent-vivid: #d9541f;
+  --color-accent-hover: #96330c;
   --color-accent-dim: rgba(198, 134, 66, 0.14);
+  --color-rose: #a8395e;
 
   /* ── Status ───────────────────────────────────────────────────────────── */
   --color-success: #6fbf8b;
@@ -60,21 +65,22 @@
   --font-sans: var(--font-inter), system-ui, -apple-system, sans-serif;
   --font-display: var(--font-fraunces), Georgia, serif;
 
-  /* A 1.2 modular scale. Display sizes are for the one hero line per screen,
-     never for a section heading. */
-  --text-display: 3.5rem;
-  --text-display--line-height: 1.02;
+  --text-hero: clamp(2.75rem, 7vw, 5.5rem);
+  --text-hero--line-height: 0.95;
+  --text-hero--letter-spacing: -0.045em;
+  --text-display: clamp(2rem, 4.5vw, 3.5rem);
+  --text-display--line-height: 1.03;
   --text-display--letter-spacing: -0.03em;
-  --text-title: 2rem;
+  --text-title: 1.75rem;
   --text-title--line-height: 1.15;
   --text-title--letter-spacing: -0.02em;
-  --text-heading: 1.25rem;
-  --text-heading--line-height: 1.3;
+  --text-heading: 1.125rem;
+  --text-heading--line-height: 1.35;
+  --text-heading--letter-spacing: -0.01em;
   --text-body: 1rem;
   --text-body--line-height: 1.6;
   --text-small: 0.875rem;
   --text-small--line-height: 1.5;
-  /* Eyebrow labels. Tracking is wide because it is always uppercase. */
   --text-label: 0.75rem;
   --text-label--line-height: 1.4;
   --text-label--letter-spacing: 0.09em;
@@ -91,6 +97,10 @@
   --shadow-glow: 0 0 0 1px rgba(198, 134, 66, 0.35),
                  0 16px 40px -20px rgba(198, 134, 66, 0.45);
 
+  /* ── Rhythm ───────────────────────────────────────────────────────────── */
+  --space-section: 5rem;
+  --space-block: 1.5rem;
+
   /* ── Motion ───────────────────────────────────────────────────────────── */
   --ease-out-soft: cubic-bezier(0.22, 1, 0.36, 1);
   --duration-fast: 140ms;
@@ -108,6 +118,7 @@
   --light-color-surface: #ffffff;
   --light-color-raised: #e8eaea;
   --light-color-overlay: rgba(247, 248, 249, 0.80);
+  --light-color-swatch-ground: #ffffff;
 
   --light-color-text: #141517;
   --light-color-text-soft: #484a4e;
@@ -139,6 +150,7 @@ html[data-theme="dark"] {
   --color-surface: #141416;
   --color-raised: #1c1c1f;
   --color-overlay: rgba(6, 6, 7, 0.72);
+  --color-swatch-ground: #ffffff;
 
   --color-text: #f5f4f2;
   --color-text-soft: #b4b1ab;
@@ -169,6 +181,7 @@ html[data-theme="light"] {
   --color-surface: var(--light-color-surface);
   --color-raised: var(--light-color-raised);
   --color-overlay: var(--light-color-overlay);
+  --color-swatch-ground: var(--light-color-swatch-ground);
 
   --color-text: var(--light-color-text);
   --color-text-soft: var(--light-color-text-soft);
@@ -197,6 +210,7 @@ html[data-theme="light"] {
     --color-surface: var(--light-color-surface);
     --color-raised: var(--light-color-raised);
     --color-overlay: var(--light-color-overlay);
+    --color-swatch-ground: var(--light-color-swatch-ground);
 
     --color-text: var(--light-color-text);
     --color-text-soft: var(--light-color-text-soft);
@@ -236,7 +250,7 @@ body {
 /* Visible, consistent focus. Never remove this without replacing it — keyboard
    users have no other way to tell where they are. */
 :focus-visible {
-  outline: 2px solid var(--color-accent-bright);
+  outline: 2px solid var(--color-accent);
   outline-offset: 2px;
   border-radius: 4px;
 }
@@ -259,7 +273,20 @@ body {
    Utilities
    ═══════════════════════════════════════════════════════════════════════════ */
 
-/* Screen-reader-only, but focusable — used by the skip link. */
+/* Always hidden visually, always present to assistive tech. */
+.sr-only {
+  position: absolute;
+  width: 1px; height: 1px;
+  padding: 0; margin: -1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* Screen-reader-only *until focused*, then shown as a real control. Only the
+   skip link should use this — on anything that can take focus it pops up as a
+   floating box in the corner. */
 .sr-only-focusable {
   position: absolute;
   width: 1px; height: 1px;
@@ -282,6 +309,31 @@ body {
   z-index: 200;
 }
 
+/* A horizontally scrolling strip shouldn't show a scrollbar over its own
+   rounded edge — the tab rail relies on this. */
+.no-scrollbar { scrollbar-width: none; -ms-overflow-style: none; }
+.no-scrollbar::-webkit-scrollbar { display: none; }
+
+/* Line clamping. Product blurbs vary in length, which left a grid of cards
+   with ragged bottom edges — the clamp is what makes a row read as a row. */
+.clamp-1, .clamp-2, .clamp-3 {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+.clamp-1 { -webkit-line-clamp: 1; }
+.clamp-2 { -webkit-line-clamp: 2; }
+.clamp-3 { -webkit-line-clamp: 3; }
+
+/* Signals that a horizontally scrolling rail continues past the edge, instead
+   of letting content look arbitrarily cut off. */
+.fade-edges {
+  -webkit-mask-image: linear-gradient(to right, transparent 0, #000 1.25rem,
+                       #000 calc(100% - 1.25rem), transparent 100%);
+  mask-image: linear-gradient(to right, transparent 0, #000 1.25rem,
+               #000 calc(100% - 1.25rem), transparent 100%);
+}
+
 /* Checkerboard behind cut-out product photos, so a transparent PNG doesn't
    vanish into the page. */
 .bg-swatch-check {
@@ -335,3 +387,35 @@ body {
     scroll-behavior: auto !important;
   }
 }
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Editorial touches
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+/* Slight rotation on alternating cards, straightening on hover. Cheap, and it
+   is most of what separates an editorial layout from a dashboard grid. */
+.tilt-a { transform: rotate(-1.4deg); }
+.tilt-b { transform: rotate(1.1deg); }
+.tilt-a, .tilt-b { transition: transform var(--duration-base) var(--ease-out-soft); }
+.tilt-a:hover, .tilt-b:hover { transform: rotate(0deg) translateY(-4px); }
+
+@media (prefers-reduced-motion: reduce) {
+  .tilt-a, .tilt-b { transform: none; }
+  .tilt-a:hover, .tilt-b:hover { transform: none; }
+}
+
+/* Warm bloom behind hero sections, so the cream ground is not flat. */
+.hero-wash {
+  position: relative;
+}
+.hero-wash::before {
+  content: "";
+  position: absolute;
+  inset: -20% -10% auto -10%;
+  height: 70%;
+  background:
+    radial-gradient(60% 60% at 20% 30%, rgba(217, 84, 31, 0.09), transparent 70%),
+    radial-gradient(50% 50% at 80% 20%, rgba(168, 57, 94, 0.07), transparent 70%);
+  pointer-events: none;
+  z-index: -1;
+}

From cd4fe713f3e5ede9d7e40177d07658b073314722 Mon Sep 17 00:00:00 2001
From: Sharanya Nagar <sharanyanagar@yahoo.in>
Date: Thu, 13 Aug 2026 08:54:10 +0530
Subject: [PATCH 04/19] refactor: centralize theme constants, preload script,
 and system preference handling

---
 frontend/app/layout.tsx                    |  3 +-
 frontend/components/layout/ThemeToggle.tsx | 44 +++++--------
 frontend/lib/theme.ts                      | 72 ++++++++++++++++++++++
 3 files changed, 88 insertions(+), 31 deletions(-)
 create mode 100644 frontend/lib/theme.ts

diff --git a/frontend/app/layout.tsx b/frontend/app/layout.tsx
index d75b7a4..a8086a0 100644
--- a/frontend/app/layout.tsx
+++ b/frontend/app/layout.tsx
@@ -2,6 +2,7 @@ import type { Metadata, Viewport } from "next";
 import { Inter, Fraunces } from "next/font/google";
 import Script from "next/script";
 import { Navbar } from "@/components/layout/Navbar";
+import { THEME_PRELOAD_SCRIPT } from "@/lib/theme";
 import "./globals.css";
 
 const inter = Inter({
@@ -41,7 +42,7 @@ export default function RootLayout({
           id="theme-preload"
           strategy="beforeInteractive"
           dangerouslySetInnerHTML={{
-            __html: `(function(){try{var t=localStorage.getItem("tinted-theme");if(t==="light"||t==="dark"){document.documentElement.setAttribute("data-theme",t);}}catch(e){}})();`,
+            __html: THEME_PRELOAD_SCRIPT,
           }}
         />
       </head>
diff --git a/frontend/components/layout/ThemeToggle.tsx b/frontend/components/layout/ThemeToggle.tsx
index cbf2c76..0567342 100644
--- a/frontend/components/layout/ThemeToggle.tsx
+++ b/frontend/components/layout/ThemeToggle.tsx
@@ -2,8 +2,12 @@
 
 import { useEffect, useState } from "react";
 import { cn } from "@/lib/utils";
-
-type ThemeMode = "system" | "light" | "dark";
+import {
+  ThemeMode,
+  THEME_STORAGE_KEY,
+  applyTheme,
+  updateMetaThemeColor,
+} from "@/lib/theme";
 
 export function ThemeToggle({ className }: { className?: string }) {
   const [theme, setTheme] = useState<ThemeMode>("system");
@@ -11,7 +15,7 @@ export function ThemeToggle({ className }: { className?: string }) {
 
   useEffect(() => {
     setMounted(true);
-    const stored = localStorage.getItem("tinted-theme") as ThemeMode | null;
+    const stored = localStorage.getItem(THEME_STORAGE_KEY) as ThemeMode | null;
     if (stored === "light" || stored === "dark" || stored === "system") {
       setTheme(stored);
     }
@@ -21,42 +25,22 @@ export function ThemeToggle({ className }: { className?: string }) {
   useEffect(() => {
     if (theme !== "system") return;
     const mediaQuery = window.matchMedia("(prefers-color-scheme: light)");
-    const handleChange = (e: MediaQueryListEvent) => {
-      const metaThemeColor = document.querySelector('meta[name="theme-color"]');
-      if (metaThemeColor) {
-        metaThemeColor.setAttribute("content", e.matches ? "#f7f8f9" : "#0b0b0c");
-      }
+    const handleChange = () => {
+      updateMetaThemeColor("system");
     };
     mediaQuery.addEventListener("change", handleChange);
     return () => mediaQuery.removeEventListener("change", handleChange);
   }, [theme]);
 
-  const updateTheme = (nextTheme: ThemeMode) => {
+  const updateThemeMode = (nextTheme: ThemeMode) => {
     setTheme(nextTheme);
-    localStorage.setItem("tinted-theme", nextTheme);
-
-    const root = document.documentElement;
-    if (nextTheme === "system") {
-      root.removeAttribute("data-theme");
-    } else {
-      root.setAttribute("data-theme", nextTheme);
-    }
-
-    // Update meta theme-color tag dynamically
-    const metaThemeColor = document.querySelector('meta[name="theme-color"]');
-    if (metaThemeColor) {
-      const isLight =
-        nextTheme === "light" ||
-        (nextTheme === "system" &&
-          window.matchMedia("(prefers-color-scheme: light)").matches);
-      metaThemeColor.setAttribute("content", isLight ? "#f7f8f9" : "#0b0b0c");
-    }
+    applyTheme(nextTheme);
   };
 
   const cycleTheme = () => {
-    if (theme === "system") updateTheme("light");
-    else if (theme === "light") updateTheme("dark");
-    else updateTheme("system");
+    if (theme === "system") updateThemeMode("light");
+    else if (theme === "light") updateThemeMode("dark");
+    else updateThemeMode("system");
   };
 
   if (!mounted) {
diff --git a/frontend/lib/theme.ts b/frontend/lib/theme.ts
new file mode 100644
index 0000000..a6ac548
--- /dev/null
+++ b/frontend/lib/theme.ts
@@ -0,0 +1,72 @@
+export type ThemeMode = "system" | "light" | "dark";
+
+export const THEME_STORAGE_KEY = "tinted-theme";
+export const THEME_COLOR_LIGHT = "#f7f8f9";
+export const THEME_COLOR_DARK = "#0b0b0c";
+
+/**
+ * Applies the specified theme mode to document.documentElement and meta[name="theme-color"].
+ * Explicitly handles "system", "light", and "dark".
+ */
+export function applyTheme(theme: ThemeMode): void {
+  if (typeof window === "undefined") return;
+
+  const root = document.documentElement;
+
+  if (theme === "system") {
+    root.removeAttribute("data-theme");
+    localStorage.setItem(THEME_STORAGE_KEY, "system");
+  } else {
+    root.setAttribute("data-theme", theme);
+    localStorage.setItem(THEME_STORAGE_KEY, theme);
+  }
+
+  updateMetaThemeColor(theme);
+}
+
+/**
+ * Updates the <meta name="theme-color"> header content based on active theme
+ * and system preference.
+ */
+export function updateMetaThemeColor(theme: ThemeMode): void {
+  if (typeof window === "undefined") return;
+
+  const metaThemeColor = document.querySelector('meta[name="theme-color"]');
+  if (!metaThemeColor) return;
+
+  const isLight =
+    theme === "light" ||
+    (theme === "system" &&
+      window.matchMedia("(prefers-color-scheme: light)").matches);
+
+  metaThemeColor.setAttribute(
+    "content",
+    isLight ? THEME_COLOR_LIGHT : THEME_COLOR_DARK,
+  );
+}
+
+/**
+ * Pre-hydration inline script string injected into <head> via next/script beforeInteractive.
+ * Handles "system", "light", and "dark" explicitly to avoid theme drift and FOUC.
+ */
+export const THEME_PRELOAD_SCRIPT = `(function() {
+  try {
+    var key = "${THEME_STORAGE_KEY}";
+    var lightColor = "${THEME_COLOR_LIGHT}";
+    var darkColor = "${THEME_COLOR_DARK}";
+    var stored = localStorage.getItem(key);
+    var root = document.documentElement;
+
+    if (stored === "light" || stored === "dark") {
+      root.setAttribute("data-theme", stored);
+    } else {
+      root.removeAttribute("data-theme");
+    }
+
+    var isLight = stored === "light" || ((!stored || stored === "system") && window.matchMedia("(prefers-color-scheme: light)").matches);
+    var meta = document.querySelector('meta[name="theme-color"]');
+    if (meta) {
+      meta.setAttribute("content", isLight ? lightColor : darkColor);
+    }
+  } catch (e) {}
+})();`;

From 0e23f161201517712f5ba740c348dc90f7d6bd98 Mon Sep 17 00:00:00 2001
From: Sharanya Nagar <sharanyanagar@yahoo.in>
Date: Thu, 13 Aug 2026 09:03:16 +0530
Subject: [PATCH 05/19] fix: resolve Tailwind CSS variable syntax and
 matchMedia listener compatibility

---
 frontend/components/layout/Navbar.tsx      |  2 +-
 frontend/components/layout/ThemeToggle.tsx | 13 ++++++++++---
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/frontend/components/layout/Navbar.tsx b/frontend/components/layout/Navbar.tsx
index 07bb34d..12b8060 100644
--- a/frontend/components/layout/Navbar.tsx
+++ b/frontend/components/layout/Navbar.tsx
@@ -49,7 +49,7 @@ export function Navbar({ className }: { className?: string }) {
                   aria-current={active ? "page" : undefined}
                   className={cn(
                     "inline-flex min-h-11 items-center whitespace-nowrap rounded-pill px-3",
-                    "text-small font-medium transition-colors duration-(--duration-fast)",
+                    "text-small font-medium transition-colors duration-[--duration-fast]",
                     active
                       ? "bg-accent-dim text-accent"
                       : "text-text-soft hover:bg-raised hover:text-text",
diff --git a/frontend/components/layout/ThemeToggle.tsx b/frontend/components/layout/ThemeToggle.tsx
index 0567342..2b2fd38 100644
--- a/frontend/components/layout/ThemeToggle.tsx
+++ b/frontend/components/layout/ThemeToggle.tsx
@@ -28,8 +28,15 @@ export function ThemeToggle({ className }: { className?: string }) {
     const handleChange = () => {
       updateMetaThemeColor("system");
     };
-    mediaQuery.addEventListener("change", handleChange);
-    return () => mediaQuery.removeEventListener("change", handleChange);
+
+    if ("addEventListener" in mediaQuery) {
+      mediaQuery.addEventListener("change", handleChange);
+      return () => mediaQuery.removeEventListener("change", handleChange);
+    } else {
+      // Fallback for older browsers (e.g. Safari < 14)
+      (mediaQuery as MediaQueryList).addListener(handleChange);
+      return () => (mediaQuery as MediaQueryList).removeListener(handleChange);
+    }
   }, [theme]);
 
   const updateThemeMode = (nextTheme: ThemeMode) => {
@@ -73,7 +80,7 @@ export function ThemeToggle({ className }: { className?: string }) {
       title={label}
       className={cn(
         "inline-flex h-9 items-center gap-1.5 rounded-pill border border-line bg-raised/60 px-2.5 py-1",
-        "text-small font-medium text-text-soft transition-colors duration-[--duration-fast]",
+        "text-small font-medium text-text-soft transition-colors duration-[var(--duration-fast)]",
         "hover:bg-raised hover:text-text focus-visible:outline-2",
         className,
       )}

From 4ea49752b59cdc3507a15d5859a44bd3df9f2a3b Mon Sep 17 00:00:00 2001
From: Sharanya Nagar <sharanyanagar@yahoo.in>
Date: Fri, 14 Aug 2026 13:15:30 +0530
Subject: [PATCH 06/19] refactor: centralize dark tokens and improve
 ThemeToggle accessibility and live OS switching

---
 frontend/app/globals.css                   | 121 ++++++++++++---------
 frontend/components/layout/ThemeToggle.tsx |  11 +-
 2 files changed, 81 insertions(+), 51 deletions(-)

diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index a1f4871..50f3997 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -33,33 +33,33 @@
 
 @theme {
   /* ── Surfaces ─────────────────────────────────────────────────────────── */
-  --color-bg: #0b0b0c;
-  --color-surface: #141416;
-  --color-raised: #1c1c1f;
-  --color-overlay: rgba(6, 6, 7, 0.72);
-  --color-swatch-ground: #ffffff;
+  --color-bg: var(--dark-color-bg);
+  --color-surface: var(--dark-color-surface);
+  --color-raised: var(--dark-color-raised);
+  --color-overlay: var(--dark-color-overlay);
+  --color-swatch-ground: var(--dark-color-swatch-ground);
 
   /* ── Text ─────────────────────────────────────────────────────────────── */
-  --color-text: #f5f4f2;
-  --color-text-soft: #b4b1ab;
-  --color-text-muted: #8a8780;
+  --color-text: var(--dark-color-text);
+  --color-text-soft: var(--dark-color-text-soft);
+  --color-text-muted: var(--dark-color-text-muted);
 
   /* ── Accent ───────────────────────────────────────────────────────────── */
-  --color-accent: #c68642;
-  --color-accent-bright: #e0a063;
+  --color-accent: var(--dark-color-accent);
+  --color-accent-bright: var(--dark-color-accent-bright);
   --color-accent-vivid: #d9541f;
   --color-accent-hover: #96330c;
-  --color-accent-dim: rgba(198, 134, 66, 0.14);
+  --color-accent-dim: var(--dark-color-accent-dim);
   --color-rose: #a8395e;
 
   /* ── Status ───────────────────────────────────────────────────────────── */
-  --color-success: #6fbf8b;
-  --color-warn: #e8b04b;
-  --color-danger: #f0796b;
+  --color-success: var(--dark-color-success);
+  --color-warn: var(--dark-color-warn);
+  --color-danger: var(--dark-color-danger);
 
   /* ── Lines ────────────────────────────────────────────────────────────── */
-  --color-line: rgba(255, 255, 255, 0.09);
-  --color-line-strong: rgba(255, 255, 255, 0.16);
+  --color-line: var(--dark-color-line);
+  --color-line-strong: var(--dark-color-line-strong);
 
   /* ── Type ─────────────────────────────────────────────────────────────── */
   --font-sans: var(--font-inter), system-ui, -apple-system, sans-serif;
@@ -95,12 +95,9 @@
   --radius-pill: 999px;
 
   /* ── Elevation ────────────────────────────────────────────────────────── */
-  --shadow-card: 0 1px 0 0 rgba(255, 255, 255, 0.05) inset,
-                 0 12px 32px -16px rgba(0, 0, 0, 0.9);
-  --shadow-lift: 0 1px 0 0 rgba(255, 255, 255, 0.07) inset,
-                 0 24px 48px -20px rgba(0, 0, 0, 0.95);
-  --shadow-glow: 0 0 0 1px rgba(198, 134, 66, 0.35),
-                 0 16px 40px -20px rgba(198, 134, 66, 0.45);
+  --shadow-card: var(--dark-shadow-card);
+  --shadow-lift: var(--dark-shadow-lift);
+  --shadow-glow: var(--dark-shadow-glow);
 
   /* ── Rhythm ───────────────────────────────────────────────────────────── */
   --space-section: 5rem;
@@ -118,6 +115,35 @@
    ═══════════════════════════════════════════════════════════════════════════ */
 
 :root {
+  /* ── Shared Dark Theme Token Definitions (Single Source of Truth) ─────── */
+  --dark-color-bg: #0b0b0c;
+  --dark-color-surface: #141416;
+  --dark-color-raised: #1c1c1f;
+  --dark-color-overlay: rgba(6, 6, 7, 0.72);
+  --dark-color-swatch-ground: #ffffff;
+
+  --dark-color-text: #f5f4f2;
+  --dark-color-text-soft: #b4b1ab;
+  --dark-color-text-muted: #8a8780;
+
+  --dark-color-accent: #c68642;
+  --dark-color-accent-bright: #e0a063;
+  --dark-color-accent-dim: rgba(198, 134, 66, 0.14);
+
+  --dark-color-success: #6fbf8b;
+  --dark-color-warn: #e8b04b;
+  --dark-color-danger: #f0796b;
+
+  --dark-color-line: rgba(255, 255, 255, 0.09);
+  --dark-color-line-strong: rgba(255, 255, 255, 0.16);
+
+  --dark-shadow-card: 0 1px 0 0 rgba(255, 255, 255, 0.05) inset,
+                      0 12px 32px -16px rgba(0, 0, 0, 0.9);
+  --dark-shadow-lift: 0 1px 0 0 rgba(255, 255, 255, 0.07) inset,
+                      0 24px 48px -20px rgba(0, 0, 0, 0.95);
+  --dark-shadow-glow: 0 0 0 1px rgba(198, 134, 66, 0.35),
+                      0 16px 40px -20px rgba(198, 134, 66, 0.45);
+
   /* ── Shared Light Theme Token Definitions (Single Source of Truth) ────── */
   --light-color-bg: #f7f8f9;
   --light-color-surface: #ffffff;
@@ -151,33 +177,30 @@
 :root,
 html[data-theme="dark"] {
   color-scheme: dark;
-  --color-bg: #0b0b0c;
-  --color-surface: #141416;
-  --color-raised: #1c1c1f;
-  --color-overlay: rgba(6, 6, 7, 0.72);
-  --color-swatch-ground: #ffffff;
-
-  --color-text: #f5f4f2;
-  --color-text-soft: #b4b1ab;
-  --color-text-muted: #8a8780;
-
-  --color-accent: #c68642;
-  --color-accent-bright: #e0a063;
-  --color-accent-dim: rgba(198, 134, 66, 0.14);
-
-  --color-success: #6fbf8b;
-  --color-warn: #e8b04b;
-  --color-danger: #f0796b;
-
-  --color-line: rgba(255, 255, 255, 0.09);
-  --color-line-strong: rgba(255, 255, 255, 0.16);
-
-  --shadow-card: 0 1px 0 0 rgba(255, 255, 255, 0.05) inset,
-                 0 12px 32px -16px rgba(0, 0, 0, 0.9);
-  --shadow-lift: 0 1px 0 0 rgba(255, 255, 255, 0.07) inset,
-                 0 24px 48px -20px rgba(0, 0, 0, 0.95);
-  --shadow-glow: 0 0 0 1px rgba(198, 134, 66, 0.35),
-                 0 16px 40px -20px rgba(198, 134, 66, 0.45);
+  --color-bg: var(--dark-color-bg);
+  --color-surface: var(--dark-color-surface);
+  --color-raised: var(--dark-color-raised);
+  --color-overlay: var(--dark-color-overlay);
+  --color-swatch-ground: var(--dark-color-swatch-ground);
+
+  --color-text: var(--dark-color-text);
+  --color-text-soft: var(--dark-color-text-soft);
+  --color-text-muted: var(--dark-color-text-muted);
+
+  --color-accent: var(--dark-color-accent);
+  --color-accent-bright: var(--dark-color-accent-bright);
+  --color-accent-dim: var(--dark-color-accent-dim);
+
+  --color-success: var(--dark-color-success);
+  --color-warn: var(--dark-color-warn);
+  --color-danger: var(--dark-color-danger);
+
+  --color-line: var(--dark-color-line);
+  --color-line-strong: var(--dark-color-line-strong);
+
+  --shadow-card: var(--dark-shadow-card);
+  --shadow-lift: var(--dark-shadow-lift);
+  --shadow-glow: var(--dark-shadow-glow);
 }
 
 html[data-theme="light"] {
diff --git a/frontend/components/layout/ThemeToggle.tsx b/frontend/components/layout/ThemeToggle.tsx
index 2b2fd38..98fec34 100644
--- a/frontend/components/layout/ThemeToggle.tsx
+++ b/frontend/components/layout/ThemeToggle.tsx
@@ -26,7 +26,7 @@ export function ThemeToggle({ className }: { className?: string }) {
     if (theme !== "system") return;
     const mediaQuery = window.matchMedia("(prefers-color-scheme: light)");
     const handleChange = () => {
-      updateMetaThemeColor("system");
+      applyTheme("system");
     };
 
     if ("addEventListener" in mediaQuery) {
@@ -66,6 +66,13 @@ export function ThemeToggle({ className }: { className?: string }) {
   }
 
   const label =
+    theme === "system"
+      ? "Theme: System"
+      : theme === "light"
+      ? "Theme: Light"
+      : "Theme: Dark";
+
+  const actionTooltip =
     theme === "system"
       ? "Theme: System (click to switch to Light)"
       : theme === "light"
@@ -77,7 +84,7 @@ export function ThemeToggle({ className }: { className?: string }) {
       type="button"
       onClick={cycleTheme}
       aria-label={label}
-      title={label}
+      title={actionTooltip}
       className={cn(
         "inline-flex h-9 items-center gap-1.5 rounded-pill border border-line bg-raised/60 px-2.5 py-1",
         "text-small font-medium text-text-soft transition-colors duration-[var(--duration-fast)]",

From 6019de42d6bfc7b0f06e700c0bda7a9c2112933b Mon Sep 17 00:00:00 2001
From: Sharanya Nagar <sharanyanagar@yahoo.in>
Date: Fri, 14 Aug 2026 13:35:35 +0530
Subject: [PATCH 07/19] refactor: tokenize accent hover/vivid states and
 improve ThemeToggle aria-label

---
 frontend/app/globals.css                   | 14 ++++++++++++--
 frontend/components/layout/Navbar.tsx      |  2 +-
 frontend/components/layout/ThemeToggle.tsx | 15 ++++-----------
 3 files changed, 17 insertions(+), 14 deletions(-)

diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index 50f3997..e2043bf 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -47,8 +47,8 @@
   /* ── Accent ───────────────────────────────────────────────────────────── */
   --color-accent: var(--dark-color-accent);
   --color-accent-bright: var(--dark-color-accent-bright);
-  --color-accent-vivid: #d9541f;
-  --color-accent-hover: #96330c;
+  --color-accent-vivid: var(--dark-color-accent-vivid);
+  --color-accent-hover: var(--dark-color-accent-hover);
   --color-accent-dim: var(--dark-color-accent-dim);
   --color-rose: #a8395e;
 
@@ -128,6 +128,8 @@
 
   --dark-color-accent: #c68642;
   --dark-color-accent-bright: #e0a063;
+  --dark-color-accent-vivid: #d9541f;
+  --dark-color-accent-hover: #96330c;
   --dark-color-accent-dim: rgba(198, 134, 66, 0.14);
 
   --dark-color-success: #6fbf8b;
@@ -157,6 +159,8 @@
 
   --light-color-accent: #875018;
   --light-color-accent-bright: #6e3e0e;
+  --light-color-accent-vivid: #b23f13;
+  --light-color-accent-hover: #5e310c;
   --light-color-accent-dim: rgba(135, 80, 24, 0.12);
 
   --light-color-success: #2b7a4b;
@@ -189,6 +193,8 @@ html[data-theme="dark"] {
 
   --color-accent: var(--dark-color-accent);
   --color-accent-bright: var(--dark-color-accent-bright);
+  --color-accent-vivid: var(--dark-color-accent-vivid);
+  --color-accent-hover: var(--dark-color-accent-hover);
   --color-accent-dim: var(--dark-color-accent-dim);
 
   --color-success: var(--dark-color-success);
@@ -217,6 +223,8 @@ html[data-theme="light"] {
 
   --color-accent: var(--light-color-accent);
   --color-accent-bright: var(--light-color-accent-bright);
+  --color-accent-vivid: var(--light-color-accent-vivid);
+  --color-accent-hover: var(--light-color-accent-hover);
   --color-accent-dim: var(--light-color-accent-dim);
 
   --color-success: var(--light-color-success);
@@ -246,6 +254,8 @@ html[data-theme="light"] {
 
     --color-accent: var(--light-color-accent);
     --color-accent-bright: var(--light-color-accent-bright);
+    --color-accent-vivid: var(--light-color-accent-vivid);
+    --color-accent-hover: var(--light-color-accent-hover);
     --color-accent-dim: var(--light-color-accent-dim);
 
     --color-success: var(--light-color-success);
diff --git a/frontend/components/layout/Navbar.tsx b/frontend/components/layout/Navbar.tsx
index 12b8060..16724b6 100644
--- a/frontend/components/layout/Navbar.tsx
+++ b/frontend/components/layout/Navbar.tsx
@@ -49,7 +49,7 @@ export function Navbar({ className }: { className?: string }) {
                   aria-current={active ? "page" : undefined}
                   className={cn(
                     "inline-flex min-h-11 items-center whitespace-nowrap rounded-pill px-3",
-                    "text-small font-medium transition-colors duration-[--duration-fast]",
+                    "text-small font-medium transition-colors duration-[var(--duration-fast)]",
                     active
                       ? "bg-accent-dim text-accent"
                       : "text-text-soft hover:bg-raised hover:text-text",
diff --git a/frontend/components/layout/ThemeToggle.tsx b/frontend/components/layout/ThemeToggle.tsx
index 98fec34..a22aa31 100644
--- a/frontend/components/layout/ThemeToggle.tsx
+++ b/frontend/components/layout/ThemeToggle.tsx
@@ -67,24 +67,17 @@ export function ThemeToggle({ className }: { className?: string }) {
 
   const label =
     theme === "system"
-      ? "Theme: System"
+      ? "Theme: System (switch to Light)"
       : theme === "light"
-      ? "Theme: Light"
-      : "Theme: Dark";
-
-  const actionTooltip =
-    theme === "system"
-      ? "Theme: System (click to switch to Light)"
-      : theme === "light"
-      ? "Theme: Light (click to switch to Dark)"
-      : "Theme: Dark (click to switch to System)";
+      ? "Theme: Light (switch to Dark)"
+      : "Theme: Dark (switch to System)";
 
   return (
     <button
       type="button"
       onClick={cycleTheme}
       aria-label={label}
-      title={actionTooltip}
+      title={label}
       className={cn(
         "inline-flex h-9 items-center gap-1.5 rounded-pill border border-line bg-raised/60 px-2.5 py-1",
         "text-small font-medium text-text-soft transition-colors duration-[var(--duration-fast)]",

From 5f73b7959345a2f9ad9015e9065066cdd48483c9 Mon Sep 17 00:00:00 2001
From: Sharanya Nagar <sharanyanagar@yahoo.in>
Date: Fri, 14 Aug 2026 13:41:02 +0530
Subject: [PATCH 08/19] fix: add try/catch storage guards, cached meta tag
 lookup, and window SSR checks

---
 frontend/components/layout/ThemeToggle.tsx | 10 +++----
 frontend/lib/theme.ts                      | 35 ++++++++++++++++++----
 2 files changed, 35 insertions(+), 10 deletions(-)

diff --git a/frontend/components/layout/ThemeToggle.tsx b/frontend/components/layout/ThemeToggle.tsx
index a22aa31..7f8d61a 100644
--- a/frontend/components/layout/ThemeToggle.tsx
+++ b/frontend/components/layout/ThemeToggle.tsx
@@ -4,9 +4,8 @@ import { useEffect, useState } from "react";
 import { cn } from "@/lib/utils";
 import {
   ThemeMode,
-  THEME_STORAGE_KEY,
+  getStoredTheme,
   applyTheme,
-  updateMetaThemeColor,
 } from "@/lib/theme";
 
 export function ThemeToggle({ className }: { className?: string }) {
@@ -15,15 +14,16 @@ export function ThemeToggle({ className }: { className?: string }) {
 
   useEffect(() => {
     setMounted(true);
-    const stored = localStorage.getItem(THEME_STORAGE_KEY) as ThemeMode | null;
-    if (stored === "light" || stored === "dark" || stored === "system") {
+    const stored = getStoredTheme();
+    if (stored) {
       setTheme(stored);
     }
   }, []);
 
   // Listen for system preference changes when in 'system' mode
   useEffect(() => {
-    if (theme !== "system") return;
+    if (typeof window === "undefined" || theme !== "system") return;
+
     const mediaQuery = window.matchMedia("(prefers-color-scheme: light)");
     const handleChange = () => {
       applyTheme("system");
diff --git a/frontend/lib/theme.ts b/frontend/lib/theme.ts
index a6ac548..1d1b4a3 100644
--- a/frontend/lib/theme.ts
+++ b/frontend/lib/theme.ts
@@ -4,6 +4,25 @@ export const THEME_STORAGE_KEY = "tinted-theme";
 export const THEME_COLOR_LIGHT = "#f7f8f9";
 export const THEME_COLOR_DARK = "#0b0b0c";
 
+let cachedMetaTag: HTMLMetaElement | null = null;
+
+/**
+ * Safely reads stored theme preference from localStorage, handling security exceptions
+ * in restricted browser environments (e.g. Safari Private Mode).
+ */
+export function getStoredTheme(): ThemeMode | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const stored = localStorage.getItem(THEME_STORAGE_KEY) as ThemeMode | null;
+    if (stored === "light" || stored === "dark" || stored === "system") {
+      return stored;
+    }
+  } catch (e) {
+    // Return null in restricted environments
+  }
+  return null;
+}
+
 /**
  * Applies the specified theme mode to document.documentElement and meta[name="theme-color"].
  * Explicitly handles "system", "light", and "dark".
@@ -15,10 +34,14 @@ export function applyTheme(theme: ThemeMode): void {
 
   if (theme === "system") {
     root.removeAttribute("data-theme");
-    localStorage.setItem(THEME_STORAGE_KEY, "system");
   } else {
     root.setAttribute("data-theme", theme);
+  }
+
+  try {
     localStorage.setItem(THEME_STORAGE_KEY, theme);
+  } catch (e) {
+    // Ignore storage write errors in restricted environments
   }
 
   updateMetaThemeColor(theme);
@@ -26,20 +49,22 @@ export function applyTheme(theme: ThemeMode): void {
 
 /**
  * Updates the <meta name="theme-color"> header content based on active theme
- * and system preference.
+ * and system preference, caching the DOM reference for performance.
  */
 export function updateMetaThemeColor(theme: ThemeMode): void {
   if (typeof window === "undefined") return;
 
-  const metaThemeColor = document.querySelector('meta[name="theme-color"]');
-  if (!metaThemeColor) return;
+  if (!cachedMetaTag || !document.contains(cachedMetaTag)) {
+    cachedMetaTag = document.querySelector('meta[name="theme-color"]');
+  }
+  if (!cachedMetaTag) return;
 
   const isLight =
     theme === "light" ||
     (theme === "system" &&
       window.matchMedia("(prefers-color-scheme: light)").matches);
 
-  metaThemeColor.setAttribute(
+  cachedMetaTag.setAttribute(
     "content",
     isLight ? THEME_COLOR_LIGHT : THEME_COLOR_DARK,
   );

From 816f180f750f6f8b5b50a35e95a0f42ebb3a4ff6 Mon Sep 17 00:00:00 2001
From: Sharanya Nagar <sharanyanagar@yahoo.in>
Date: Fri, 14 Aug 2026 13:47:24 +0530
Subject: [PATCH 09/19] fix: add HTMLMetaElement type assertion for
 cachedMetaTag query in theme.ts

---
 frontend/lib/theme.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend/lib/theme.ts b/frontend/lib/theme.ts
index 1d1b4a3..5dc8c36 100644
--- a/frontend/lib/theme.ts
+++ b/frontend/lib/theme.ts
@@ -55,7 +55,7 @@ export function updateMetaThemeColor(theme: ThemeMode): void {
   if (typeof window === "undefined") return;
 
   if (!cachedMetaTag || !document.contains(cachedMetaTag)) {
-    cachedMetaTag = document.querySelector('meta[name="theme-color"]');
+    cachedMetaTag = document.querySelector('meta[name="theme-color"]') as HTMLMetaElement | null;
   }
   if (!cachedMetaTag) return;
 

From 8ea92be6744f871548ac2c61fa7c85bf9ee62fb4 Mon Sep 17 00:00:00 2001
From: Sharanya Nagar <sharanyanagar@yahoo.in>
Date: Fri, 14 Aug 2026 13:51:35 +0530
Subject: [PATCH 10/19] refactor: apply custom property indirection and
 immediate OS theme evaluation

---
 frontend/app/globals.css                   | 216 +++++++++++++--------
 frontend/components/layout/ThemeToggle.tsx |   5 +-
 2 files changed, 141 insertions(+), 80 deletions(-)

diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index e2043bf..e06b029 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -178,99 +178,157 @@
                        0 8px 24px -6px rgba(135, 80, 24, 0.25);
 }
 
-:root,
+  /* ── Default Active Theme Slot Assignment ─────────────────────────────── */
+  --active-bg: var(--dark-color-bg);
+  --active-surface: var(--dark-color-surface);
+  --active-raised: var(--dark-color-raised);
+  --active-overlay: var(--dark-color-overlay);
+  --active-swatch-ground: var(--dark-color-swatch-ground);
+
+  --active-text: var(--dark-color-text);
+  --active-text-soft: var(--dark-color-text-soft);
+  --active-text-muted: var(--dark-color-text-muted);
+
+  --active-accent: var(--dark-color-accent);
+  --active-accent-bright: var(--dark-color-accent-bright);
+  --active-accent-vivid: var(--dark-color-accent-vivid);
+  --active-accent-hover: var(--dark-color-accent-hover);
+  --active-accent-dim: var(--dark-color-accent-dim);
+
+  --active-success: var(--dark-color-success);
+  --active-warn: var(--dark-color-warn);
+  --active-danger: var(--dark-color-danger);
+
+  --active-line: var(--dark-color-line);
+  --active-line-strong: var(--dark-color-line-strong);
+
+  --active-shadow-card: var(--dark-shadow-card);
+  --active-shadow-lift: var(--dark-shadow-lift);
+  --active-shadow-glow: var(--dark-shadow-glow);
+}
+
 html[data-theme="dark"] {
   color-scheme: dark;
-  --color-bg: var(--dark-color-bg);
-  --color-surface: var(--dark-color-surface);
-  --color-raised: var(--dark-color-raised);
-  --color-overlay: var(--dark-color-overlay);
-  --color-swatch-ground: var(--dark-color-swatch-ground);
-
-  --color-text: var(--dark-color-text);
-  --color-text-soft: var(--dark-color-text-soft);
-  --color-text-muted: var(--dark-color-text-muted);
-
-  --color-accent: var(--dark-color-accent);
-  --color-accent-bright: var(--dark-color-accent-bright);
-  --color-accent-vivid: var(--dark-color-accent-vivid);
-  --color-accent-hover: var(--dark-color-accent-hover);
-  --color-accent-dim: var(--dark-color-accent-dim);
-
-  --color-success: var(--dark-color-success);
-  --color-warn: var(--dark-color-warn);
-  --color-danger: var(--dark-color-danger);
-
-  --color-line: var(--dark-color-line);
-  --color-line-strong: var(--dark-color-line-strong);
-
-  --shadow-card: var(--dark-shadow-card);
-  --shadow-lift: var(--dark-shadow-lift);
-  --shadow-glow: var(--dark-shadow-glow);
+  --active-bg: var(--dark-color-bg);
+  --active-surface: var(--dark-color-surface);
+  --active-raised: var(--dark-color-raised);
+  --active-overlay: var(--dark-color-overlay);
+  --active-swatch-ground: var(--dark-color-swatch-ground);
+
+  --active-text: var(--dark-color-text);
+  --active-text-soft: var(--dark-color-text-soft);
+  --active-text-muted: var(--dark-color-text-muted);
+
+  --active-accent: var(--dark-color-accent);
+  --active-accent-bright: var(--dark-color-accent-bright);
+  --active-accent-vivid: var(--dark-color-accent-vivid);
+  --active-accent-hover: var(--dark-color-accent-hover);
+  --active-accent-dim: var(--dark-color-accent-dim);
+
+  --active-success: var(--dark-color-success);
+  --active-warn: var(--dark-color-warn);
+  --active-danger: var(--dark-color-danger);
+
+  --active-line: var(--dark-color-line);
+  --active-line-strong: var(--dark-color-line-strong);
+
+  --active-shadow-card: var(--dark-shadow-card);
+  --active-shadow-lift: var(--dark-shadow-lift);
+  --active-shadow-glow: var(--dark-shadow-glow);
 }
 
 html[data-theme="light"] {
   color-scheme: light;
-  --color-bg: var(--light-color-bg);
-  --color-surface: var(--light-color-surface);
-  --color-raised: var(--light-color-raised);
-  --color-overlay: var(--light-color-overlay);
-  --color-swatch-ground: var(--light-color-swatch-ground);
-
-  --color-text: var(--light-color-text);
-  --color-text-soft: var(--light-color-text-soft);
-  --color-text-muted: var(--light-color-text-muted);
-
-  --color-accent: var(--light-color-accent);
-  --color-accent-bright: var(--light-color-accent-bright);
-  --color-accent-vivid: var(--light-color-accent-vivid);
-  --color-accent-hover: var(--light-color-accent-hover);
-  --color-accent-dim: var(--light-color-accent-dim);
-
-  --color-success: var(--light-color-success);
-  --color-warn: var(--light-color-warn);
-  --color-danger: var(--light-color-danger);
-
-  --color-line: var(--light-color-line);
-  --color-line-strong: var(--light-color-line-strong);
-
-  --shadow-card: var(--light-shadow-card);
-  --shadow-lift: var(--light-shadow-lift);
-  --shadow-glow: var(--light-shadow-glow);
+  --active-bg: var(--light-color-bg);
+  --active-surface: var(--light-color-surface);
+  --active-raised: var(--light-color-raised);
+  --active-overlay: var(--light-color-overlay);
+  --active-swatch-ground: var(--light-color-swatch-ground);
+
+  --active-text: var(--light-color-text);
+  --active-text-soft: var(--light-color-text-soft);
+  --active-text-muted: var(--light-color-text-muted);
+
+  --active-accent: var(--light-color-accent);
+  --active-accent-bright: var(--light-color-accent-bright);
+  --active-accent-vivid: var(--light-color-accent-vivid);
+  --active-accent-hover: var(--light-color-accent-hover);
+  --active-accent-dim: var(--light-color-accent-dim);
+
+  --active-success: var(--light-color-success);
+  --active-warn: var(--light-color-warn);
+  --active-danger: var(--light-color-danger);
+
+  --active-line: var(--light-color-line);
+  --active-line-strong: var(--light-color-line-strong);
+
+  --active-shadow-card: var(--light-shadow-card);
+  --active-shadow-lift: var(--light-shadow-lift);
+  --active-shadow-glow: var(--light-shadow-glow);
 }
 
 @media (prefers-color-scheme: light) {
   :root:not([data-theme="dark"]) {
     color-scheme: light;
-    --color-bg: var(--light-color-bg);
-    --color-surface: var(--light-color-surface);
-    --color-raised: var(--light-color-raised);
-    --color-overlay: var(--light-color-overlay);
-    --color-swatch-ground: var(--light-color-swatch-ground);
-
-    --color-text: var(--light-color-text);
-    --color-text-soft: var(--light-color-text-soft);
-    --color-text-muted: var(--light-color-text-muted);
-
-    --color-accent: var(--light-color-accent);
-    --color-accent-bright: var(--light-color-accent-bright);
-    --color-accent-vivid: var(--light-color-accent-vivid);
-    --color-accent-hover: var(--light-color-accent-hover);
-    --color-accent-dim: var(--light-color-accent-dim);
-
-    --color-success: var(--light-color-success);
-    --color-warn: var(--light-color-warn);
-    --color-danger: var(--light-color-danger);
-
-    --color-line: var(--light-color-line);
-    --color-line-strong: var(--light-color-line-strong);
-
-    --shadow-card: var(--light-shadow-card);
-    --shadow-lift: var(--light-shadow-lift);
-    --shadow-glow: var(--light-shadow-glow);
+    --active-bg: var(--light-color-bg);
+    --active-surface: var(--light-color-surface);
+    --active-raised: var(--light-color-raised);
+    --active-overlay: var(--light-color-overlay);
+    --active-swatch-ground: var(--light-color-swatch-ground);
+
+    --active-text: var(--light-color-text);
+    --active-text-soft: var(--light-color-text-soft);
+    --active-text-muted: var(--light-color-text-muted);
+
+    --active-accent: var(--light-color-accent);
+    --active-accent-bright: var(--light-color-accent-bright);
+    --active-accent-vivid: var(--light-color-accent-vivid);
+    --active-accent-hover: var(--light-color-accent-hover);
+    --active-accent-dim: var(--light-color-accent-dim);
+
+    --active-success: var(--light-color-success);
+    --active-warn: var(--light-color-warn);
+    --active-danger: var(--light-color-danger);
+
+    --active-line: var(--light-color-line);
+    --active-line-strong: var(--light-color-line-strong);
+
+    --active-shadow-card: var(--light-shadow-card);
+    --active-shadow-lift: var(--light-shadow-lift);
+    --active-shadow-glow: var(--light-shadow-glow);
   }
 }
 
+/* Single Universal Token Map */
+:root {
+  --color-bg: var(--active-bg);
+  --color-surface: var(--active-surface);
+  --color-raised: var(--active-raised);
+  --color-overlay: var(--active-overlay);
+  --color-swatch-ground: var(--active-swatch-ground);
+
+  --color-text: var(--active-text);
+  --color-text-soft: var(--active-text-soft);
+  --color-text-muted: var(--active-text-muted);
+
+  --color-accent: var(--active-accent);
+  --color-accent-bright: var(--active-accent-bright);
+  --color-accent-vivid: var(--active-accent-vivid);
+  --color-accent-hover: var(--active-accent-hover);
+  --color-accent-dim: var(--active-accent-dim);
+
+  --color-success: var(--active-success);
+  --color-warn: var(--active-warn);
+  --color-danger: var(--active-danger);
+
+  --color-line: var(--active-line);
+  --color-line-strong: var(--active-line-strong);
+
+  --shadow-card: var(--active-shadow-card);
+  --shadow-lift: var(--active-shadow-lift);
+  --shadow-glow: var(--active-shadow-glow);
+}
+
 /* ═══════════════════════════════════════════════════════════════════════════
    Base
    ═══════════════════════════════════════════════════════════════════════════ */
diff --git a/frontend/components/layout/ThemeToggle.tsx b/frontend/components/layout/ThemeToggle.tsx
index 7f8d61a..69a8409 100644
--- a/frontend/components/layout/ThemeToggle.tsx
+++ b/frontend/components/layout/ThemeToggle.tsx
@@ -20,10 +20,13 @@ export function ThemeToggle({ className }: { className?: string }) {
     }
   }, []);
 
-  // Listen for system preference changes when in 'system' mode
+  // Listen for system preference changes when in 'system' mode, and immediately re-evaluate on entering system mode
   useEffect(() => {
     if (typeof window === "undefined" || theme !== "system") return;
 
+    // Immediately sync DOM attributes & meta header with current OS theme
+    applyTheme("system");
+
     const mediaQuery = window.matchMedia("(prefers-color-scheme: light)");
     const handleChange = () => {
       applyTheme("system");

From 5ecb7935fba17c6793f019d1f76d4fccfbfb88dd Mon Sep 17 00:00:00 2001
From: Sharanya Nagar <sharanyanagar@yahoo.in>
Date: Fri, 14 Aug 2026 13:54:53 +0530
Subject: [PATCH 11/19] fix: enclose default active theme variables inside
 :root selector in globals.css

---
 frontend/app/globals.css | 65 ++++++++++++++++++----------------------
 1 file changed, 29 insertions(+), 36 deletions(-)

diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index e06b029..96c7b97 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -65,11 +65,6 @@
   --font-sans: var(--font-inter), system-ui, -apple-system, sans-serif;
   --font-display: var(--font-fraunces), Georgia, serif;
 
-  /* Scale runs ~1.33 at the top and ~1.2 lower down. The previous 1.2
-     throughout meant a page heading and a section heading were one step
-     apart, which is why everything read as the same weight — flat hierarchy
-     is most of what "generic" actually means. Hero is deliberately far from
-     everything else: one per page, and it should dominate. */
   --text-hero: clamp(2.75rem, 7vw, 5.5rem);
   --text-hero--line-height: 0.95;
   --text-hero--letter-spacing: -0.045em;
@@ -176,7 +171,6 @@
                        0 12px 28px -6px rgba(0, 0, 0, 0.12);
   --light-shadow-glow: 0 0 0 1px rgba(135, 80, 24, 0.30),
                        0 8px 24px -6px rgba(135, 80, 24, 0.25);
-}
 
   /* ── Default Active Theme Slot Assignment ─────────────────────────────── */
   --active-bg: var(--dark-color-bg);
@@ -205,6 +199,35 @@
   --active-shadow-card: var(--dark-shadow-card);
   --active-shadow-lift: var(--dark-shadow-lift);
   --active-shadow-glow: var(--dark-shadow-glow);
+
+  /* ── Single Mapping of Active Slots to Design Tokens ───────────────────── */
+  color-scheme: dark;
+  --color-bg: var(--active-bg);
+  --color-surface: var(--active-surface);
+  --color-raised: var(--active-raised);
+  --color-overlay: var(--active-overlay);
+  --color-swatch-ground: var(--active-swatch-ground);
+
+  --color-text: var(--active-text);
+  --color-text-soft: var(--active-text-soft);
+  --color-text-muted: var(--active-text-muted);
+
+  --color-accent: var(--active-accent);
+  --color-accent-bright: var(--active-accent-bright);
+  --color-accent-vivid: var(--active-accent-vivid);
+  --color-accent-hover: var(--active-accent-hover);
+  --color-accent-dim: var(--active-accent-dim);
+
+  --color-success: var(--active-success);
+  --color-warn: var(--active-warn);
+  --color-danger: var(--active-danger);
+
+  --color-line: var(--active-line);
+  --color-line-strong: var(--active-line-strong);
+
+  --shadow-card: var(--active-shadow-card);
+  --shadow-lift: var(--active-shadow-lift);
+  --shadow-glow: var(--active-shadow-glow);
 }
 
 html[data-theme="dark"] {
@@ -299,36 +322,6 @@ html[data-theme="light"] {
   }
 }
 
-/* Single Universal Token Map */
-:root {
-  --color-bg: var(--active-bg);
-  --color-surface: var(--active-surface);
-  --color-raised: var(--active-raised);
-  --color-overlay: var(--active-overlay);
-  --color-swatch-ground: var(--active-swatch-ground);
-
-  --color-text: var(--active-text);
-  --color-text-soft: var(--active-text-soft);
-  --color-text-muted: var(--active-text-muted);
-
-  --color-accent: var(--active-accent);
-  --color-accent-bright: var(--active-accent-bright);
-  --color-accent-vivid: var(--active-accent-vivid);
-  --color-accent-hover: var(--active-accent-hover);
-  --color-accent-dim: var(--active-accent-dim);
-
-  --color-success: var(--active-success);
-  --color-warn: var(--active-warn);
-  --color-danger: var(--active-danger);
-
-  --color-line: var(--active-line);
-  --color-line-strong: var(--active-line-strong);
-
-  --shadow-card: var(--active-shadow-card);
-  --shadow-lift: var(--active-shadow-lift);
-  --shadow-glow: var(--active-shadow-glow);
-}
-
 /* ═══════════════════════════════════════════════════════════════════════════
    Base
    ═══════════════════════════════════════════════════════════════════════════ */

From c5a9519fba58a6d767b276763ab0bd7800d21ed2 Mon Sep 17 00:00:00 2001
From: Sharanya Nagar <sharanyanagar@yahoo.in>
Date: Fri, 14 Aug 2026 13:59:17 +0530
Subject: [PATCH 12/19] refactor: simplify theme token rules in globals.css and
 align pre-hydration inline script

---
 frontend/app/globals.css | 332 +++++++++++++--------------------------
 frontend/lib/theme.ts    |  57 +++----
 2 files changed, 138 insertions(+), 251 deletions(-)

diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index 96c7b97..9e21811 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -33,33 +33,33 @@
 
 @theme {
   /* ── Surfaces ─────────────────────────────────────────────────────────── */
-  --color-bg: var(--dark-color-bg);
-  --color-surface: var(--dark-color-surface);
-  --color-raised: var(--dark-color-raised);
-  --color-overlay: var(--dark-color-overlay);
-  --color-swatch-ground: var(--dark-color-swatch-ground);
+  --color-bg: #0b0b0c;
+  --color-surface: #141416;
+  --color-raised: #1c1c1f;
+  --color-overlay: rgba(6, 6, 7, 0.72);
+  --color-swatch-ground: #ffffff;
 
   /* ── Text ─────────────────────────────────────────────────────────────── */
-  --color-text: var(--dark-color-text);
-  --color-text-soft: var(--dark-color-text-soft);
-  --color-text-muted: var(--dark-color-text-muted);
+  --color-text: #f5f4f2;
+  --color-text-soft: #b4b1ab;
+  --color-text-muted: #8a8780;
 
   /* ── Accent ───────────────────────────────────────────────────────────── */
-  --color-accent: var(--dark-color-accent);
-  --color-accent-bright: var(--dark-color-accent-bright);
-  --color-accent-vivid: var(--dark-color-accent-vivid);
-  --color-accent-hover: var(--dark-color-accent-hover);
-  --color-accent-dim: var(--dark-color-accent-dim);
+  --color-accent: #c68642;
+  --color-accent-bright: #e0a063;
+  --color-accent-vivid: #d9541f;
+  --color-accent-hover: #96330c;
+  --color-accent-dim: rgba(198, 134, 66, 0.14);
   --color-rose: #a8395e;
 
   /* ── Status ───────────────────────────────────────────────────────────── */
-  --color-success: var(--dark-color-success);
-  --color-warn: var(--dark-color-warn);
-  --color-danger: var(--dark-color-danger);
+  --color-success: #6fbf8b;
+  --color-warn: #e8b04b;
+  --color-danger: #f0796b;
 
   /* ── Lines ────────────────────────────────────────────────────────────── */
-  --color-line: var(--dark-color-line);
-  --color-line-strong: var(--dark-color-line-strong);
+  --color-line: rgba(255, 255, 255, 0.09);
+  --color-line-strong: rgba(255, 255, 255, 0.16);
 
   /* ── Type ─────────────────────────────────────────────────────────────── */
   --font-sans: var(--font-inter), system-ui, -apple-system, sans-serif;
@@ -90,9 +90,12 @@
   --radius-pill: 999px;
 
   /* ── Elevation ────────────────────────────────────────────────────────── */
-  --shadow-card: var(--dark-shadow-card);
-  --shadow-lift: var(--dark-shadow-lift);
-  --shadow-glow: var(--dark-shadow-glow);
+  --shadow-card: 0 1px 0 0 rgba(255, 255, 255, 0.05) inset,
+                 0 12px 32px -16px rgba(0, 0, 0, 0.9);
+  --shadow-lift: 0 1px 0 0 rgba(255, 255, 255, 0.07) inset,
+                 0 24px 48px -20px rgba(0, 0, 0, 0.95);
+  --shadow-glow: 0 0 0 1px rgba(198, 134, 66, 0.35),
+                 0 16px 40px -20px rgba(198, 134, 66, 0.45);
 
   /* ── Rhythm ───────────────────────────────────────────────────────────── */
   --space-section: 5rem;
@@ -109,216 +112,105 @@
    Theme Token Rules
    ═══════════════════════════════════════════════════════════════════════════ */
 
-:root {
-  /* ── Shared Dark Theme Token Definitions (Single Source of Truth) ─────── */
-  --dark-color-bg: #0b0b0c;
-  --dark-color-surface: #141416;
-  --dark-color-raised: #1c1c1f;
-  --dark-color-overlay: rgba(6, 6, 7, 0.72);
-  --dark-color-swatch-ground: #ffffff;
-
-  --dark-color-text: #f5f4f2;
-  --dark-color-text-soft: #b4b1ab;
-  --dark-color-text-muted: #8a8780;
-
-  --dark-color-accent: #c68642;
-  --dark-color-accent-bright: #e0a063;
-  --dark-color-accent-vivid: #d9541f;
-  --dark-color-accent-hover: #96330c;
-  --dark-color-accent-dim: rgba(198, 134, 66, 0.14);
-
-  --dark-color-success: #6fbf8b;
-  --dark-color-warn: #e8b04b;
-  --dark-color-danger: #f0796b;
-
-  --dark-color-line: rgba(255, 255, 255, 0.09);
-  --dark-color-line-strong: rgba(255, 255, 255, 0.16);
-
-  --dark-shadow-card: 0 1px 0 0 rgba(255, 255, 255, 0.05) inset,
-                      0 12px 32px -16px rgba(0, 0, 0, 0.9);
-  --dark-shadow-lift: 0 1px 0 0 rgba(255, 255, 255, 0.07) inset,
-                      0 24px 48px -20px rgba(0, 0, 0, 0.95);
-  --dark-shadow-glow: 0 0 0 1px rgba(198, 134, 66, 0.35),
-                      0 16px 40px -20px rgba(198, 134, 66, 0.45);
-
-  /* ── Shared Light Theme Token Definitions (Single Source of Truth) ────── */
-  --light-color-bg: #f7f8f9;
-  --light-color-surface: #ffffff;
-  --light-color-raised: #e8eaea;
-  --light-color-overlay: rgba(247, 248, 249, 0.80);
-  --light-color-swatch-ground: #ffffff;
-
-  --light-color-text: #141517;
-  --light-color-text-soft: #484a4e;
-  --light-color-text-muted: #616368;
-
-  --light-color-accent: #875018;
-  --light-color-accent-bright: #6e3e0e;
-  --light-color-accent-vivid: #b23f13;
-  --light-color-accent-hover: #5e310c;
-  --light-color-accent-dim: rgba(135, 80, 24, 0.12);
-
-  --light-color-success: #2b7a4b;
-  --light-color-warn: #a36209;
-  --light-color-danger: #cf3b2b;
-
-  --light-color-line: rgba(0, 0, 0, 0.08);
-  --light-color-line-strong: rgba(0, 0, 0, 0.16);
-
-  --light-shadow-card: 0 1px 3px 0 rgba(0, 0, 0, 0.06),
-                       0 4px 12px -2px rgba(0, 0, 0, 0.08);
-  --light-shadow-lift: 0 4px 16px -2px rgba(0, 0, 0, 0.10),
-                       0 12px 28px -6px rgba(0, 0, 0, 0.12);
-  --light-shadow-glow: 0 0 0 1px rgba(135, 80, 24, 0.30),
-                       0 8px 24px -6px rgba(135, 80, 24, 0.25);
-
-  /* ── Default Active Theme Slot Assignment ─────────────────────────────── */
-  --active-bg: var(--dark-color-bg);
-  --active-surface: var(--dark-color-surface);
-  --active-raised: var(--dark-color-raised);
-  --active-overlay: var(--dark-color-overlay);
-  --active-swatch-ground: var(--dark-color-swatch-ground);
-
-  --active-text: var(--dark-color-text);
-  --active-text-soft: var(--dark-color-text-soft);
-  --active-text-muted: var(--dark-color-text-muted);
-
-  --active-accent: var(--dark-color-accent);
-  --active-accent-bright: var(--dark-color-accent-bright);
-  --active-accent-vivid: var(--dark-color-accent-vivid);
-  --active-accent-hover: var(--dark-color-accent-hover);
-  --active-accent-dim: var(--dark-color-accent-dim);
-
-  --active-success: var(--dark-color-success);
-  --active-warn: var(--dark-color-warn);
-  --active-danger: var(--dark-color-danger);
-
-  --active-line: var(--dark-color-line);
-  --active-line-strong: var(--dark-color-line-strong);
-
-  --active-shadow-card: var(--dark-shadow-card);
-  --active-shadow-lift: var(--dark-shadow-lift);
-  --active-shadow-glow: var(--dark-shadow-glow);
-
-  /* ── Single Mapping of Active Slots to Design Tokens ───────────────────── */
-  color-scheme: dark;
-  --color-bg: var(--active-bg);
-  --color-surface: var(--active-surface);
-  --color-raised: var(--active-raised);
-  --color-overlay: var(--active-overlay);
-  --color-swatch-ground: var(--active-swatch-ground);
-
-  --color-text: var(--active-text);
-  --color-text-soft: var(--active-text-soft);
-  --color-text-muted: var(--active-text-muted);
-
-  --color-accent: var(--active-accent);
-  --color-accent-bright: var(--active-accent-bright);
-  --color-accent-vivid: var(--active-accent-vivid);
-  --color-accent-hover: var(--active-accent-hover);
-  --color-accent-dim: var(--active-accent-dim);
-
-  --color-success: var(--active-success);
-  --color-warn: var(--active-warn);
-  --color-danger: var(--active-danger);
-
-  --color-line: var(--active-line);
-  --color-line-strong: var(--active-line-strong);
-
-  --shadow-card: var(--active-shadow-card);
-  --shadow-lift: var(--active-shadow-lift);
-  --shadow-glow: var(--active-shadow-glow);
-}
-
+:root,
 html[data-theme="dark"] {
   color-scheme: dark;
-  --active-bg: var(--dark-color-bg);
-  --active-surface: var(--dark-color-surface);
-  --active-raised: var(--dark-color-raised);
-  --active-overlay: var(--dark-color-overlay);
-  --active-swatch-ground: var(--dark-color-swatch-ground);
-
-  --active-text: var(--dark-color-text);
-  --active-text-soft: var(--dark-color-text-soft);
-  --active-text-muted: var(--dark-color-text-muted);
-
-  --active-accent: var(--dark-color-accent);
-  --active-accent-bright: var(--dark-color-accent-bright);
-  --active-accent-vivid: var(--dark-color-accent-vivid);
-  --active-accent-hover: var(--dark-color-accent-hover);
-  --active-accent-dim: var(--dark-color-accent-dim);
-
-  --active-success: var(--dark-color-success);
-  --active-warn: var(--dark-color-warn);
-  --active-danger: var(--dark-color-danger);
-
-  --active-line: var(--dark-color-line);
-  --active-line-strong: var(--dark-color-line-strong);
-
-  --active-shadow-card: var(--dark-shadow-card);
-  --active-shadow-lift: var(--dark-shadow-lift);
-  --active-shadow-glow: var(--dark-shadow-glow);
+  --color-bg: #0b0b0c;
+  --color-surface: #141416;
+  --color-raised: #1c1c1f;
+  --color-overlay: rgba(6, 6, 7, 0.72);
+  --color-swatch-ground: #ffffff;
+
+  --color-text: #f5f4f2;
+  --color-text-soft: #b4b1ab;
+  --color-text-muted: #8a8780;
+
+  --color-accent: #c68642;
+  --color-accent-bright: #e0a063;
+  --color-accent-vivid: #d9541f;
+  --color-accent-hover: #96330c;
+  --color-accent-dim: rgba(198, 134, 66, 0.14);
+
+  --color-success: #6fbf8b;
+  --color-warn: #e8b04b;
+  --color-danger: #f0796b;
+
+  --color-line: rgba(255, 255, 255, 0.09);
+  --color-line-strong: rgba(255, 255, 255, 0.16);
+
+  --shadow-card: 0 1px 0 0 rgba(255, 255, 255, 0.05) inset,
+                 0 12px 32px -16px rgba(0, 0, 0, 0.9);
+  --shadow-lift: 0 1px 0 0 rgba(255, 255, 255, 0.07) inset,
+                 0 24px 48px -20px rgba(0, 0, 0, 0.95);
+  --shadow-glow: 0 0 0 1px rgba(198, 134, 66, 0.35),
+                 0 16px 40px -20px rgba(198, 134, 66, 0.45);
 }
 
 html[data-theme="light"] {
   color-scheme: light;
-  --active-bg: var(--light-color-bg);
-  --active-surface: var(--light-color-surface);
-  --active-raised: var(--light-color-raised);
-  --active-overlay: var(--light-color-overlay);
-  --active-swatch-ground: var(--light-color-swatch-ground);
-
-  --active-text: var(--light-color-text);
-  --active-text-soft: var(--light-color-text-soft);
-  --active-text-muted: var(--light-color-text-muted);
-
-  --active-accent: var(--light-color-accent);
-  --active-accent-bright: var(--light-color-accent-bright);
-  --active-accent-vivid: var(--light-color-accent-vivid);
-  --active-accent-hover: var(--light-color-accent-hover);
-  --active-accent-dim: var(--light-color-accent-dim);
-
-  --active-success: var(--light-color-success);
-  --active-warn: var(--light-color-warn);
-  --active-danger: var(--light-color-danger);
-
-  --active-line: var(--light-color-line);
-  --active-line-strong: var(--light-color-line-strong);
-
-  --active-shadow-card: var(--light-shadow-card);
-  --active-shadow-lift: var(--light-shadow-lift);
-  --active-shadow-glow: var(--light-shadow-glow);
+  --color-bg: #f7f8f9;
+  --color-surface: #ffffff;
+  --color-raised: #e8eaea;
+  --color-overlay: rgba(247, 248, 249, 0.80);
+  --color-swatch-ground: #ffffff;
+
+  --color-text: #141517;
+  --color-text-soft: #484a4e;
+  --color-text-muted: #616368;
+
+  --color-accent: #875018;
+  --color-accent-bright: #6e3e0e;
+  --color-accent-vivid: #b23f13;
+  --color-accent-hover: #5e310c;
+  --color-accent-dim: rgba(135, 80, 24, 0.12);
+
+  --color-success: #2b7a4b;
+  --color-warn: #a36209;
+  --color-danger: #cf3b2b;
+
+  --color-line: rgba(0, 0, 0, 0.08);
+  --color-line-strong: rgba(0, 0, 0, 0.16);
+
+  --shadow-card: 0 1px 3px 0 rgba(0, 0, 0, 0.06),
+                 0 4px 12px -2px rgba(0, 0, 0, 0.08);
+  --shadow-lift: 0 4px 16px -2px rgba(0, 0, 0, 0.10),
+                 0 12px 28px -6px rgba(0, 0, 0, 0.12);
+  --shadow-glow: 0 0 0 1px rgba(135, 80, 24, 0.30),
+                 0 8px 24px -6px rgba(135, 80, 24, 0.25);
 }
 
 @media (prefers-color-scheme: light) {
   :root:not([data-theme="dark"]) {
     color-scheme: light;
-    --active-bg: var(--light-color-bg);
-    --active-surface: var(--light-color-surface);
-    --active-raised: var(--light-color-raised);
-    --active-overlay: var(--light-color-overlay);
-    --active-swatch-ground: var(--light-color-swatch-ground);
-
-    --active-text: var(--light-color-text);
-    --active-text-soft: var(--light-color-text-soft);
-    --active-text-muted: var(--light-color-text-muted);
-
-    --active-accent: var(--light-color-accent);
-    --active-accent-bright: var(--light-color-accent-bright);
-    --active-accent-vivid: var(--light-color-accent-vivid);
-    --active-accent-hover: var(--light-color-accent-hover);
-    --active-accent-dim: var(--light-color-accent-dim);
-
-    --active-success: var(--light-color-success);
-    --active-warn: var(--light-color-warn);
-    --active-danger: var(--light-color-danger);
-
-    --active-line: var(--light-color-line);
-    --active-line-strong: var(--light-color-line-strong);
-
-    --active-shadow-card: var(--light-shadow-card);
-    --active-shadow-lift: var(--light-shadow-lift);
-    --active-shadow-glow: var(--light-shadow-glow);
+    --color-bg: #f7f8f9;
+    --color-surface: #ffffff;
+    --color-raised: #e8eaea;
+    --color-overlay: rgba(247, 248, 249, 0.80);
+    --color-swatch-ground: #ffffff;
+
+    --color-text: #141517;
+    --color-text-soft: #484a4e;
+    --color-text-muted: #616368;
+
+    --color-accent: #875018;
+    --color-accent-bright: #6e3e0e;
+    --color-accent-vivid: #b23f13;
+    --color-accent-hover: #5e310c;
+    --color-accent-dim: rgba(135, 80, 24, 0.12);
+
+    --color-success: #2b7a4b;
+    --color-warn: #a36209;
+    --color-danger: #cf3b2b;
+
+    --color-line: rgba(0, 0, 0, 0.08);
+    --color-line-strong: rgba(0, 0, 0, 0.16);
+
+    --shadow-card: 0 1px 3px 0 rgba(0, 0, 0, 0.06),
+                   0 4px 12px -2px rgba(0, 0, 0, 0.08);
+    --shadow-lift: 0 4px 16px -2px rgba(0, 0, 0, 0.10),
+                   0 12px 28px -6px rgba(0, 0, 0, 0.12);
+    --shadow-glow: 0 0 0 1px rgba(135, 80, 24, 0.30),
+                   0 8px 24px -6px rgba(135, 80, 24, 0.25);
   }
 }
 
diff --git a/frontend/lib/theme.ts b/frontend/lib/theme.ts
index 5dc8c36..db6648e 100644
--- a/frontend/lib/theme.ts
+++ b/frontend/lib/theme.ts
@@ -23,6 +23,29 @@ export function getStoredTheme(): ThemeMode | null {
   return null;
 }
 
+/**
+ * Updates the <meta name="theme-color"> header content based on active theme
+ * and system preference, caching the DOM reference for performance.
+ */
+export function updateMetaThemeColor(theme: ThemeMode): void {
+  if (typeof window === "undefined") return;
+
+  if (!cachedMetaTag || !document.contains(cachedMetaTag)) {
+    cachedMetaTag = document.querySelector('meta[name="theme-color"]') as HTMLMetaElement | null;
+  }
+  if (!cachedMetaTag) return;
+
+  const isLight =
+    theme === "light" ||
+    (theme === "system" &&
+      window.matchMedia("(prefers-color-scheme: light)").matches);
+
+  cachedMetaTag.setAttribute(
+    "content",
+    isLight ? THEME_COLOR_LIGHT : THEME_COLOR_DARK,
+  );
+}
+
 /**
  * Applies the specified theme mode to document.documentElement and meta[name="theme-color"].
  * Explicitly handles "system", "light", and "dark".
@@ -47,51 +70,23 @@ export function applyTheme(theme: ThemeMode): void {
   updateMetaThemeColor(theme);
 }
 
-/**
- * Updates the <meta name="theme-color"> header content based on active theme
- * and system preference, caching the DOM reference for performance.
- */
-export function updateMetaThemeColor(theme: ThemeMode): void {
-  if (typeof window === "undefined") return;
-
-  if (!cachedMetaTag || !document.contains(cachedMetaTag)) {
-    cachedMetaTag = document.querySelector('meta[name="theme-color"]') as HTMLMetaElement | null;
-  }
-  if (!cachedMetaTag) return;
-
-  const isLight =
-    theme === "light" ||
-    (theme === "system" &&
-      window.matchMedia("(prefers-color-scheme: light)").matches);
-
-  cachedMetaTag.setAttribute(
-    "content",
-    isLight ? THEME_COLOR_LIGHT : THEME_COLOR_DARK,
-  );
-}
-
 /**
  * Pre-hydration inline script string injected into <head> via next/script beforeInteractive.
- * Handles "system", "light", and "dark" explicitly to avoid theme drift and FOUC.
+ * Aligned directly with applyTheme and updateMetaThemeColor to prevent theme drift.
  */
 export const THEME_PRELOAD_SCRIPT = `(function() {
   try {
-    var key = "${THEME_STORAGE_KEY}";
-    var lightColor = "${THEME_COLOR_LIGHT}";
-    var darkColor = "${THEME_COLOR_DARK}";
-    var stored = localStorage.getItem(key);
+    var stored = localStorage.getItem("${THEME_STORAGE_KEY}");
     var root = document.documentElement;
-
     if (stored === "light" || stored === "dark") {
       root.setAttribute("data-theme", stored);
     } else {
       root.removeAttribute("data-theme");
     }
-
     var isLight = stored === "light" || ((!stored || stored === "system") && window.matchMedia("(prefers-color-scheme: light)").matches);
     var meta = document.querySelector('meta[name="theme-color"]');
     if (meta) {
-      meta.setAttribute("content", isLight ? lightColor : darkColor);
+      meta.setAttribute("content", isLight ? "${THEME_COLOR_LIGHT}" : "${THEME_COLOR_DARK}");
     }
   } catch (e) {}
 })();`;

From d81ad2e659f329065ed105016890ca5c1aa98a8a Mon Sep 17 00:00:00 2001
From: Sharanya Nagar <sharanyanagar@yahoo.in>
Date: Fri, 14 Aug 2026 14:03:32 +0530
Subject: [PATCH 13/19] refactor: simplify @theme variables and centralize
 light theme tokens

---
 frontend/app/globals.css | 239 ++++++++++++++++++++++++---------------
 1 file changed, 148 insertions(+), 91 deletions(-)

diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index 9e21811..d027614 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -32,34 +32,34 @@
    ═══════════════════════════════════════════════════════════════════════════ */
 
 @theme {
-  /* ── Surfaces ─────────────────────────────────────────────────────────── */
-  --color-bg: #0b0b0c;
-  --color-surface: #141416;
-  --color-raised: #1c1c1f;
-  --color-overlay: rgba(6, 6, 7, 0.72);
-  --color-swatch-ground: #ffffff;
-
-  /* ── Text ─────────────────────────────────────────────────────────────── */
-  --color-text: #f5f4f2;
-  --color-text-soft: #b4b1ab;
-  --color-text-muted: #8a8780;
-
-  /* ── Accent ───────────────────────────────────────────────────────────── */
-  --color-accent: #c68642;
-  --color-accent-bright: #e0a063;
-  --color-accent-vivid: #d9541f;
-  --color-accent-hover: #96330c;
-  --color-accent-dim: rgba(198, 134, 66, 0.14);
+  /* ── Dynamic Surfaces ─────────────────────────────────────────────────── */
+  --color-bg: var(--color-bg);
+  --color-surface: var(--color-surface);
+  --color-raised: var(--color-raised);
+  --color-overlay: var(--color-overlay);
+  --color-swatch-ground: var(--color-swatch-ground);
+
+  /* ── Dynamic Text ─────────────────────────────────────────────────────── */
+  --color-text: var(--color-text);
+  --color-text-soft: var(--color-text-soft);
+  --color-text-muted: var(--color-text-muted);
+
+  /* ── Dynamic Accent ───────────────────────────────────────────────────── */
+  --color-accent: var(--color-accent);
+  --color-accent-bright: var(--color-accent-bright);
+  --color-accent-vivid: var(--color-accent-vivid);
+  --color-accent-hover: var(--color-accent-hover);
+  --color-accent-dim: var(--color-accent-dim);
   --color-rose: #a8395e;
 
-  /* ── Status ───────────────────────────────────────────────────────────── */
-  --color-success: #6fbf8b;
-  --color-warn: #e8b04b;
-  --color-danger: #f0796b;
+  /* ── Dynamic Status ───────────────────────────────────────────────────── */
+  --color-success: var(--color-success);
+  --color-warn: var(--color-warn);
+  --color-danger: var(--color-danger);
 
-  /* ── Lines ────────────────────────────────────────────────────────────── */
-  --color-line: rgba(255, 255, 255, 0.09);
-  --color-line-strong: rgba(255, 255, 255, 0.16);
+  /* ── Dynamic Lines ────────────────────────────────────────────────────── */
+  --color-line: var(--color-line);
+  --color-line-strong: var(--color-line-strong);
 
   /* ── Type ─────────────────────────────────────────────────────────────── */
   --font-sans: var(--font-inter), system-ui, -apple-system, sans-serif;
@@ -89,13 +89,10 @@
   --radius-card: 0.875rem;
   --radius-pill: 999px;
 
-  /* ── Elevation ────────────────────────────────────────────────────────── */
-  --shadow-card: 0 1px 0 0 rgba(255, 255, 255, 0.05) inset,
-                 0 12px 32px -16px rgba(0, 0, 0, 0.9);
-  --shadow-lift: 0 1px 0 0 rgba(255, 255, 255, 0.07) inset,
-                 0 24px 48px -20px rgba(0, 0, 0, 0.95);
-  --shadow-glow: 0 0 0 1px rgba(198, 134, 66, 0.35),
-                 0 16px 40px -20px rgba(198, 134, 66, 0.45);
+  /* ── Dynamic Elevation ────────────────────────────────────────────────── */
+  --shadow-card: var(--shadow-card);
+  --shadow-lift: var(--shadow-lift);
+  --shadow-glow: var(--shadow-glow);
 
   /* ── Rhythm ───────────────────────────────────────────────────────────── */
   --space-section: 5rem;
@@ -112,7 +109,71 @@
    Theme Token Rules
    ═══════════════════════════════════════════════════════════════════════════ */
 
-:root,
+:root {
+  /* ── Single Source of Truth: Light Theme Values ────────────────────────── */
+  --light-color-bg: #f7f8f9;
+  --light-color-surface: #ffffff;
+  --light-color-raised: #e8eaea;
+  --light-color-overlay: rgba(247, 248, 249, 0.80);
+  --light-color-swatch-ground: #ffffff;
+
+  --light-color-text: #141517;
+  --light-color-text-soft: #484a4e;
+  --light-color-text-muted: #616368;
+
+  --light-color-accent: #875018;
+  --light-color-accent-bright: #6e3e0e;
+  --light-color-accent-vivid: #b23f13;
+  --light-color-accent-hover: #5e310c;
+  --light-color-accent-dim: rgba(135, 80, 24, 0.12);
+
+  --light-color-success: #2b7a4b;
+  --light-color-warn: #a36209;
+  --light-color-danger: #cf3b2b;
+
+  --light-color-line: rgba(0, 0, 0, 0.08);
+  --light-color-line-strong: rgba(0, 0, 0, 0.16);
+
+  --light-shadow-card: 0 1px 3px 0 rgba(0, 0, 0, 0.06),
+                       0 4px 12px -2px rgba(0, 0, 0, 0.08);
+  --light-shadow-lift: 0 4px 16px -2px rgba(0, 0, 0, 0.10),
+                       0 12px 28px -6px rgba(0, 0, 0, 0.12);
+  --light-shadow-glow: 0 0 0 1px rgba(135, 80, 24, 0.30),
+                       0 8px 24px -6px rgba(135, 80, 24, 0.25);
+
+  /* ── Dark Theme Defaults ───────────────────────────────────────────────── */
+  color-scheme: dark;
+  --color-bg: #0b0b0c;
+  --color-surface: #141416;
+  --color-raised: #1c1c1f;
+  --color-overlay: rgba(6, 6, 7, 0.72);
+  --color-swatch-ground: #ffffff;
+
+  --color-text: #f5f4f2;
+  --color-text-soft: #b4b1ab;
+  --color-text-muted: #8a8780;
+
+  --color-accent: #c68642;
+  --color-accent-bright: #e0a063;
+  --color-accent-vivid: #d9541f;
+  --color-accent-hover: #96330c;
+  --color-accent-dim: rgba(198, 134, 66, 0.14);
+
+  --color-success: #6fbf8b;
+  --color-warn: #e8b04b;
+  --color-danger: #f0796b;
+
+  --color-line: rgba(255, 255, 255, 0.09);
+  --color-line-strong: rgba(255, 255, 255, 0.16);
+
+  --shadow-card: 0 1px 0 0 rgba(255, 255, 255, 0.05) inset,
+                 0 12px 32px -16px rgba(0, 0, 0, 0.9);
+  --shadow-lift: 0 1px 0 0 rgba(255, 255, 255, 0.07) inset,
+                 0 24px 48px -20px rgba(0, 0, 0, 0.95);
+  --shadow-glow: 0 0 0 1px rgba(198, 134, 66, 0.35),
+                 0 16px 40px -20px rgba(198, 134, 66, 0.45);
+}
+
 html[data-theme="dark"] {
   color-scheme: dark;
   --color-bg: #0b0b0c;
@@ -146,71 +207,67 @@ html[data-theme="dark"] {
                  0 16px 40px -20px rgba(198, 134, 66, 0.45);
 }
 
+/* Shared Light Theme Token Rule */
+.theme-light,
 html[data-theme="light"] {
   color-scheme: light;
-  --color-bg: #f7f8f9;
-  --color-surface: #ffffff;
-  --color-raised: #e8eaea;
-  --color-overlay: rgba(247, 248, 249, 0.80);
-  --color-swatch-ground: #ffffff;
-
-  --color-text: #141517;
-  --color-text-soft: #484a4e;
-  --color-text-muted: #616368;
-
-  --color-accent: #875018;
-  --color-accent-bright: #6e3e0e;
-  --color-accent-vivid: #b23f13;
-  --color-accent-hover: #5e310c;
-  --color-accent-dim: rgba(135, 80, 24, 0.12);
-
-  --color-success: #2b7a4b;
-  --color-warn: #a36209;
-  --color-danger: #cf3b2b;
-
-  --color-line: rgba(0, 0, 0, 0.08);
-  --color-line-strong: rgba(0, 0, 0, 0.16);
-
-  --shadow-card: 0 1px 3px 0 rgba(0, 0, 0, 0.06),
-                 0 4px 12px -2px rgba(0, 0, 0, 0.08);
-  --shadow-lift: 0 4px 16px -2px rgba(0, 0, 0, 0.10),
-                 0 12px 28px -6px rgba(0, 0, 0, 0.12);
-  --shadow-glow: 0 0 0 1px rgba(135, 80, 24, 0.30),
-                 0 8px 24px -6px rgba(135, 80, 24, 0.25);
+  --color-bg: var(--light-color-bg);
+  --color-surface: var(--light-color-surface);
+  --color-raised: var(--light-color-raised);
+  --color-overlay: var(--light-color-overlay);
+  --color-swatch-ground: var(--light-color-swatch-ground);
+
+  --color-text: var(--light-color-text);
+  --color-text-soft: var(--light-color-text-soft);
+  --color-text-muted: var(--light-color-text-muted);
+
+  --color-accent: var(--light-color-accent);
+  --color-accent-bright: var(--light-color-accent-bright);
+  --color-accent-vivid: var(--light-color-accent-vivid);
+  --color-accent-hover: var(--light-color-accent-hover);
+  --color-accent-dim: var(--light-color-accent-dim);
+
+  --color-success: var(--light-color-success);
+  --color-warn: var(--light-color-warn);
+  --color-danger: var(--light-color-danger);
+
+  --color-line: var(--light-color-line);
+  --color-line-strong: var(--light-color-line-strong);
+
+  --shadow-card: var(--light-shadow-card);
+  --shadow-lift: var(--light-shadow-lift);
+  --shadow-glow: var(--light-shadow-glow);
 }
 
 @media (prefers-color-scheme: light) {
   :root:not([data-theme="dark"]) {
     color-scheme: light;
-    --color-bg: #f7f8f9;
-    --color-surface: #ffffff;
-    --color-raised: #e8eaea;
-    --color-overlay: rgba(247, 248, 249, 0.80);
-    --color-swatch-ground: #ffffff;
-
-    --color-text: #141517;
-    --color-text-soft: #484a4e;
-    --color-text-muted: #616368;
-
-    --color-accent: #875018;
-    --color-accent-bright: #6e3e0e;
-    --color-accent-vivid: #b23f13;
-    --color-accent-hover: #5e310c;
-    --color-accent-dim: rgba(135, 80, 24, 0.12);
-
-    --color-success: #2b7a4b;
-    --color-warn: #a36209;
-    --color-danger: #cf3b2b;
-
-    --color-line: rgba(0, 0, 0, 0.08);
-    --color-line-strong: rgba(0, 0, 0, 0.16);
-
-    --shadow-card: 0 1px 3px 0 rgba(0, 0, 0, 0.06),
-                   0 4px 12px -2px rgba(0, 0, 0, 0.08);
-    --shadow-lift: 0 4px 16px -2px rgba(0, 0, 0, 0.10),
-                   0 12px 28px -6px rgba(0, 0, 0, 0.12);
-    --shadow-glow: 0 0 0 1px rgba(135, 80, 24, 0.30),
-                   0 8px 24px -6px rgba(135, 80, 24, 0.25);
+    --color-bg: var(--light-color-bg);
+    --color-surface: var(--light-color-surface);
+    --color-raised: var(--light-color-raised);
+    --color-overlay: var(--light-color-overlay);
+    --color-swatch-ground: var(--light-color-swatch-ground);
+
+    --color-text: var(--light-color-text);
+    --color-text-soft: var(--light-color-text-soft);
+    --color-text-muted: var(--light-color-text-muted);
+
+    --color-accent: var(--light-color-accent);
+    --color-accent-bright: var(--light-color-accent-bright);
+    --color-accent-vivid: var(--light-color-accent-vivid);
+    --color-accent-hover: var(--light-color-accent-hover);
+    --color-accent-dim: var(--light-color-accent-dim);
+
+    --color-success: var(--light-color-success);
+    --color-warn: var(--light-color-warn);
+    --color-danger: var(--light-color-danger);
+
+    --color-line: var(--light-color-line);
+    --color-line-strong: var(--light-color-line-strong);
+
+    --shadow-card: var(--light-shadow-card);
+    --shadow-lift: var(--light-shadow-lift);
+    --shadow-glow: var(--light-shadow-glow);
   }
 }
 

From 3d2802e919dc34d3870b451d2ba6d70991bdaa23 Mon Sep 17 00:00:00 2001
From: Sharanya Nagar <sharanyanagar@yahoo.in>
Date: Fri, 14 Aug 2026 14:08:24 +0530
Subject: [PATCH 14/19] refactor: centralize dark theme tokens and share theme
 decision logic

---
 frontend/app/globals.css | 143 +++++++++++++++++++++++----------------
 frontend/lib/theme.ts    |  52 +++++++++++---
 2 files changed, 126 insertions(+), 69 deletions(-)

diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index d027614..82aedea 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -141,70 +141,97 @@
   --light-shadow-glow: 0 0 0 1px rgba(135, 80, 24, 0.30),
                        0 8px 24px -6px rgba(135, 80, 24, 0.25);
 
+  /* ── Single Source of Truth: Dark Theme Values ─────────────────────────── */
+  --dark-color-bg: #0b0b0c;
+  --dark-color-surface: #141416;
+  --dark-color-raised: #1c1c1f;
+  --dark-color-overlay: rgba(6, 6, 7, 0.72);
+  --dark-color-swatch-ground: #ffffff;
+
+  --dark-color-text: #f5f4f2;
+  --dark-color-text-soft: #b4b1ab;
+  --dark-color-text-muted: #8a8780;
+
+  --dark-color-accent: #c68642;
+  --dark-color-accent-bright: #e0a063;
+  --dark-color-accent-vivid: #d9541f;
+  --dark-color-accent-hover: #96330c;
+  --dark-color-accent-dim: rgba(198, 134, 66, 0.14);
+
+  --dark-color-success: #6fbf8b;
+  --dark-color-warn: #e8b04b;
+  --dark-color-danger: #f0796b;
+
+  --dark-color-line: rgba(255, 255, 255, 0.09);
+  --dark-color-line-strong: rgba(255, 255, 255, 0.16);
+
+  --dark-shadow-card: 0 1px 0 0 rgba(255, 255, 255, 0.05) inset,
+                      0 12px 32px -16px rgba(0, 0, 0, 0.9);
+  --dark-shadow-lift: 0 1px 0 0 rgba(255, 255, 255, 0.07) inset,
+                      0 24px 48px -20px rgba(0, 0, 0, 0.95);
+  --dark-shadow-glow: 0 0 0 1px rgba(198, 134, 66, 0.35),
+                      0 16px 40px -20px rgba(198, 134, 66, 0.45);
+
   /* ── Dark Theme Defaults ───────────────────────────────────────────────── */
   color-scheme: dark;
-  --color-bg: #0b0b0c;
-  --color-surface: #141416;
-  --color-raised: #1c1c1f;
-  --color-overlay: rgba(6, 6, 7, 0.72);
-  --color-swatch-ground: #ffffff;
-
-  --color-text: #f5f4f2;
-  --color-text-soft: #b4b1ab;
-  --color-text-muted: #8a8780;
-
-  --color-accent: #c68642;
-  --color-accent-bright: #e0a063;
-  --color-accent-vivid: #d9541f;
-  --color-accent-hover: #96330c;
-  --color-accent-dim: rgba(198, 134, 66, 0.14);
-
-  --color-success: #6fbf8b;
-  --color-warn: #e8b04b;
-  --color-danger: #f0796b;
-
-  --color-line: rgba(255, 255, 255, 0.09);
-  --color-line-strong: rgba(255, 255, 255, 0.16);
-
-  --shadow-card: 0 1px 0 0 rgba(255, 255, 255, 0.05) inset,
-                 0 12px 32px -16px rgba(0, 0, 0, 0.9);
-  --shadow-lift: 0 1px 0 0 rgba(255, 255, 255, 0.07) inset,
-                 0 24px 48px -20px rgba(0, 0, 0, 0.95);
-  --shadow-glow: 0 0 0 1px rgba(198, 134, 66, 0.35),
-                 0 16px 40px -20px rgba(198, 134, 66, 0.45);
+  --color-bg: var(--dark-color-bg);
+  --color-surface: var(--dark-color-surface);
+  --color-raised: var(--dark-color-raised);
+  --color-overlay: var(--dark-color-overlay);
+  --color-swatch-ground: var(--dark-color-swatch-ground);
+
+  --color-text: var(--dark-color-text);
+  --color-text-soft: var(--dark-color-text-soft);
+  --color-text-muted: var(--dark-color-text-muted);
+
+  --color-accent: var(--dark-color-accent);
+  --color-accent-bright: var(--dark-color-accent-bright);
+  --color-accent-vivid: var(--dark-color-accent-vivid);
+  --color-accent-hover: var(--dark-color-accent-hover);
+  --color-accent-dim: var(--dark-color-accent-dim);
+
+  --color-success: var(--dark-color-success);
+  --color-warn: var(--dark-color-warn);
+  --color-danger: var(--dark-color-danger);
+
+  --color-line: var(--dark-color-line);
+  --color-line-strong: var(--dark-color-line-strong);
+
+  --shadow-card: var(--dark-shadow-card);
+  --shadow-lift: var(--dark-shadow-lift);
+  --shadow-glow: var(--dark-shadow-glow);
 }
 
+/* Shared Dark Theme Token Rule */
+.theme-dark,
 html[data-theme="dark"] {
   color-scheme: dark;
-  --color-bg: #0b0b0c;
-  --color-surface: #141416;
-  --color-raised: #1c1c1f;
-  --color-overlay: rgba(6, 6, 7, 0.72);
-  --color-swatch-ground: #ffffff;
-
-  --color-text: #f5f4f2;
-  --color-text-soft: #b4b1ab;
-  --color-text-muted: #8a8780;
-
-  --color-accent: #c68642;
-  --color-accent-bright: #e0a063;
-  --color-accent-vivid: #d9541f;
-  --color-accent-hover: #96330c;
-  --color-accent-dim: rgba(198, 134, 66, 0.14);
-
-  --color-success: #6fbf8b;
-  --color-warn: #e8b04b;
-  --color-danger: #f0796b;
-
-  --color-line: rgba(255, 255, 255, 0.09);
-  --color-line-strong: rgba(255, 255, 255, 0.16);
-
-  --shadow-card: 0 1px 0 0 rgba(255, 255, 255, 0.05) inset,
-                 0 12px 32px -16px rgba(0, 0, 0, 0.9);
-  --shadow-lift: 0 1px 0 0 rgba(255, 255, 255, 0.07) inset,
-                 0 24px 48px -20px rgba(0, 0, 0, 0.95);
-  --shadow-glow: 0 0 0 1px rgba(198, 134, 66, 0.35),
-                 0 16px 40px -20px rgba(198, 134, 66, 0.45);
+  --color-bg: var(--dark-color-bg);
+  --color-surface: var(--dark-color-surface);
+  --color-raised: var(--dark-color-raised);
+  --color-overlay: var(--dark-color-overlay);
+  --color-swatch-ground: var(--dark-color-swatch-ground);
+
+  --color-text: var(--dark-color-text);
+  --color-text-soft: var(--dark-color-text-soft);
+  --color-text-muted: var(--dark-color-text-muted);
+
+  --color-accent: var(--dark-color-accent);
+  --color-accent-bright: var(--dark-color-accent-bright);
+  --color-accent-vivid: var(--dark-color-accent-vivid);
+  --color-accent-hover: var(--dark-color-accent-hover);
+  --color-accent-dim: var(--dark-color-accent-dim);
+
+  --color-success: var(--dark-color-success);
+  --color-warn: var(--dark-color-warn);
+  --color-danger: var(--dark-color-danger);
+
+  --color-line: var(--dark-color-line);
+  --color-line-strong: var(--dark-color-line-strong);
+
+  --shadow-card: var(--dark-shadow-card);
+  --shadow-lift: var(--dark-shadow-lift);
+  --shadow-glow: var(--dark-shadow-glow);
 }
 
 /* Shared Light Theme Token Rule */
diff --git a/frontend/lib/theme.ts b/frontend/lib/theme.ts
index db6648e..11b9bcb 100644
--- a/frontend/lib/theme.ts
+++ b/frontend/lib/theme.ts
@@ -6,6 +6,31 @@ export const THEME_COLOR_DARK = "#0b0b0c";
 
 let cachedMetaTag: HTMLMetaElement | null = null;
 
+/**
+ * Returns the HTML data-theme attribute value for a given theme mode or raw stored string,
+ * or null if theme is "system", missing, or unrecognised.
+ */
+export function getThemeAttribute(theme: string | null): "light" | "dark" | null {
+  return theme === "light" || theme === "dark" ? theme : null;
+}
+
+/**
+ * Resolves whether a theme mode (or raw stored value) evaluates to light mode.
+ */
+export function isLightTheme(theme: string | null, prefersLight: boolean): boolean {
+  return theme === "light" || ((!theme || theme === "system") && prefersLight);
+}
+
+/**
+ * Resolves the effective theme mode ("light" or "dark") based on theme preference and system OS setting.
+ */
+export function resolveEffectiveTheme(
+  theme: string | null,
+  prefersLight: boolean,
+): "light" | "dark" {
+  return isLightTheme(theme, prefersLight) ? "light" : "dark";
+}
+
 /**
  * Safely reads stored theme preference from localStorage, handling security exceptions
  * in restricted browser environments (e.g. Safari Private Mode).
@@ -35,10 +60,8 @@ export function updateMetaThemeColor(theme: ThemeMode): void {
   }
   if (!cachedMetaTag) return;
 
-  const isLight =
-    theme === "light" ||
-    (theme === "system" &&
-      window.matchMedia("(prefers-color-scheme: light)").matches);
+  const prefersLight = window.matchMedia("(prefers-color-scheme: light)").matches;
+  const isLight = isLightTheme(theme, prefersLight);
 
   cachedMetaTag.setAttribute(
     "content",
@@ -54,11 +77,12 @@ export function applyTheme(theme: ThemeMode): void {
   if (typeof window === "undefined") return;
 
   const root = document.documentElement;
+  const attr = getThemeAttribute(theme);
 
-  if (theme === "system") {
-    root.removeAttribute("data-theme");
+  if (attr) {
+    root.setAttribute("data-theme", attr);
   } else {
-    root.setAttribute("data-theme", theme);
+    root.removeAttribute("data-theme");
   }
 
   try {
@@ -72,18 +96,24 @@ export function applyTheme(theme: ThemeMode): void {
 
 /**
  * Pre-hydration inline script string injected into <head> via next/script beforeInteractive.
- * Aligned directly with applyTheme and updateMetaThemeColor to prevent theme drift.
+ * Reuses the core getThemeAttribute and isLightTheme decision logic functions to prevent theme drift.
  */
 export const THEME_PRELOAD_SCRIPT = `(function() {
   try {
+    var getThemeAttribute = ${getThemeAttribute.toString()};
+    var isLightTheme = ${isLightTheme.toString()};
+
     var stored = localStorage.getItem("${THEME_STORAGE_KEY}");
     var root = document.documentElement;
-    if (stored === "light" || stored === "dark") {
-      root.setAttribute("data-theme", stored);
+    var attr = getThemeAttribute(stored);
+    if (attr) {
+      root.setAttribute("data-theme", attr);
     } else {
       root.removeAttribute("data-theme");
     }
-    var isLight = stored === "light" || ((!stored || stored === "system") && window.matchMedia("(prefers-color-scheme: light)").matches);
+
+    var prefersLight = window.matchMedia("(prefers-color-scheme: light)").matches;
+    var isLight = isLightTheme(stored, prefersLight);
     var meta = document.querySelector('meta[name="theme-color"]');
     if (meta) {
       meta.setAttribute("content", isLight ? "${THEME_COLOR_LIGHT}" : "${THEME_COLOR_DARK}");

From 2574a2c6a2a8f0149a82b6ef8fa3d341a3194c07 Mon Sep 17 00:00:00 2001
From: Sharanya Nagar <sharanyanagar@yahoo.in>
Date: Fri, 14 Aug 2026 14:14:44 +0530
Subject: [PATCH 15/19] refactor: simplify preload script string and optimize
 ThemeToggle mount listener

---
 frontend/components/layout/ThemeToggle.tsx | 27 ++++++++++------------
 frontend/lib/theme.ts                      | 12 ++++------
 2 files changed, 16 insertions(+), 23 deletions(-)

diff --git a/frontend/components/layout/ThemeToggle.tsx b/frontend/components/layout/ThemeToggle.tsx
index 69a8409..7e98e8b 100644
--- a/frontend/components/layout/ThemeToggle.tsx
+++ b/frontend/components/layout/ThemeToggle.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { cn } from "@/lib/utils";
 import {
   ThemeMode,
@@ -12,24 +12,21 @@ export function ThemeToggle({ className }: { className?: string }) {
   const [theme, setTheme] = useState<ThemeMode>("system");
   const [mounted, setMounted] = useState(false);
 
-  useEffect(() => {
-    setMounted(true);
-    const stored = getStoredTheme();
-    if (stored) {
-      setTheme(stored);
-    }
-  }, []);
+  // Keep a ref to the latest active theme mode to allow a persistent matchMedia listener without re-attaching
+  const themeRef = useRef(theme);
+  themeRef.current = theme;
 
-  // Listen for system preference changes when in 'system' mode, and immediately re-evaluate on entering system mode
   useEffect(() => {
-    if (typeof window === "undefined" || theme !== "system") return;
-
-    // Immediately sync DOM attributes & meta header with current OS theme
-    applyTheme("system");
+    setMounted(true);
+    const stored = getStoredTheme() ?? "system";
+    setTheme(stored);
+    applyTheme(stored);
 
     const mediaQuery = window.matchMedia("(prefers-color-scheme: light)");
     const handleChange = () => {
-      applyTheme("system");
+      if (themeRef.current === "system") {
+        applyTheme("system");
+      }
     };
 
     if ("addEventListener" in mediaQuery) {
@@ -40,7 +37,7 @@ export function ThemeToggle({ className }: { className?: string }) {
       (mediaQuery as MediaQueryList).addListener(handleChange);
       return () => (mediaQuery as MediaQueryList).removeListener(handleChange);
     }
-  }, [theme]);
+  }, []);
 
   const updateThemeMode = (nextTheme: ThemeMode) => {
     setTheme(nextTheme);
diff --git a/frontend/lib/theme.ts b/frontend/lib/theme.ts
index 11b9bcb..8a54200 100644
--- a/frontend/lib/theme.ts
+++ b/frontend/lib/theme.ts
@@ -96,24 +96,20 @@ export function applyTheme(theme: ThemeMode): void {
 
 /**
  * Pre-hydration inline script string injected into <head> via next/script beforeInteractive.
- * Reuses the core getThemeAttribute and isLightTheme decision logic functions to prevent theme drift.
+ * Written as a self-contained inline script string to avoid brittleness under bundler minification.
  */
 export const THEME_PRELOAD_SCRIPT = `(function() {
   try {
-    var getThemeAttribute = ${getThemeAttribute.toString()};
-    var isLightTheme = ${isLightTheme.toString()};
-
     var stored = localStorage.getItem("${THEME_STORAGE_KEY}");
     var root = document.documentElement;
-    var attr = getThemeAttribute(stored);
-    if (attr) {
-      root.setAttribute("data-theme", attr);
+    if (stored === "light" || stored === "dark") {
+      root.setAttribute("data-theme", stored);
     } else {
       root.removeAttribute("data-theme");
     }
 
     var prefersLight = window.matchMedia("(prefers-color-scheme: light)").matches;
-    var isLight = isLightTheme(stored, prefersLight);
+    var isLight = stored === "light" || ((!stored || stored === "system") && prefersLight);
     var meta = document.querySelector('meta[name="theme-color"]');
     if (meta) {
       meta.setAttribute("content", isLight ? "${THEME_COLOR_LIGHT}" : "${THEME_COLOR_DARK}");

From f26208a6d67672d73bd854021af2e7297d10f4b0 Mon Sep 17 00:00:00 2001
From: Sharanya Nagar <sharanyanagar@yahoo.in>
Date: Fri, 14 Aug 2026 14:18:05 +0530
Subject: [PATCH 16/19] refactor: consolidate dark theme CSS selectors and
 centralize meta theme color resolution

---
 frontend/app/globals.css | 31 ++-----------------------------
 frontend/app/layout.tsx  |  1 +
 frontend/lib/theme.ts    | 14 ++++++++------
 3 files changed, 11 insertions(+), 35 deletions(-)

diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index 82aedea..07ae5f7 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -172,37 +172,10 @@
   --dark-shadow-glow: 0 0 0 1px rgba(198, 134, 66, 0.35),
                       0 16px 40px -20px rgba(198, 134, 66, 0.45);
 
-  /* ── Dark Theme Defaults ───────────────────────────────────────────────── */
-  color-scheme: dark;
-  --color-bg: var(--dark-color-bg);
-  --color-surface: var(--dark-color-surface);
-  --color-raised: var(--dark-color-raised);
-  --color-overlay: var(--dark-color-overlay);
-  --color-swatch-ground: var(--dark-color-swatch-ground);
-
-  --color-text: var(--dark-color-text);
-  --color-text-soft: var(--dark-color-text-soft);
-  --color-text-muted: var(--dark-color-text-muted);
-
-  --color-accent: var(--dark-color-accent);
-  --color-accent-bright: var(--dark-color-accent-bright);
-  --color-accent-vivid: var(--dark-color-accent-vivid);
-  --color-accent-hover: var(--dark-color-accent-hover);
-  --color-accent-dim: var(--dark-color-accent-dim);
-
-  --color-success: var(--dark-color-success);
-  --color-warn: var(--dark-color-warn);
-  --color-danger: var(--dark-color-danger);
-
-  --color-line: var(--dark-color-line);
-  --color-line-strong: var(--dark-color-line-strong);
-
-  --shadow-card: var(--dark-shadow-card);
-  --shadow-lift: var(--dark-shadow-lift);
-  --shadow-glow: var(--dark-shadow-glow);
+  /* ── Dark Theme Defaults & Centralized Selector ────────────────────────── */
 }
 
-/* Shared Dark Theme Token Rule */
+:root,
 .theme-dark,
 html[data-theme="dark"] {
   color-scheme: dark;
diff --git a/frontend/app/layout.tsx b/frontend/app/layout.tsx
index a8086a0..86835a6 100644
--- a/frontend/app/layout.tsx
+++ b/frontend/app/layout.tsx
@@ -36,6 +36,7 @@ export default function RootLayout({
   children: React.ReactNode;
 }) {
   return (
+    {/* suppressHydrationWarning is placed on <html> strictly for the data-theme attribute injected pre-hydration by THEME_PRELOAD_SCRIPT. React only suppresses attribute warnings on <html> itself. */}
     <html lang="en" className={`${inter.variable} ${fraunces.variable}`} suppressHydrationWarning>
       <head>
         <Script
diff --git a/frontend/lib/theme.ts b/frontend/lib/theme.ts
index 8a54200..d424cb2 100644
--- a/frontend/lib/theme.ts
+++ b/frontend/lib/theme.ts
@@ -31,6 +31,13 @@ export function resolveEffectiveTheme(
   return isLightTheme(theme, prefersLight) ? "light" : "dark";
 }
 
+/**
+ * Resolves the theme color hex string for meta[name="theme-color"].
+ */
+export function resolveMetaThemeColor(theme: string | null, prefersLight: boolean): string {
+  return isLightTheme(theme, prefersLight) ? THEME_COLOR_LIGHT : THEME_COLOR_DARK;
+}
+
 /**
  * Safely reads stored theme preference from localStorage, handling security exceptions
  * in restricted browser environments (e.g. Safari Private Mode).
@@ -61,12 +68,7 @@ export function updateMetaThemeColor(theme: ThemeMode): void {
   if (!cachedMetaTag) return;
 
   const prefersLight = window.matchMedia("(prefers-color-scheme: light)").matches;
-  const isLight = isLightTheme(theme, prefersLight);
-
-  cachedMetaTag.setAttribute(
-    "content",
-    isLight ? THEME_COLOR_LIGHT : THEME_COLOR_DARK,
-  );
+  cachedMetaTag.setAttribute("content", resolveMetaThemeColor(theme, prefersLight));
 }
 
 /**

From ebf7d3838eb53140ebc3d78016b02ef886493d9d Mon Sep 17 00:00:00 2001
From: Sharanya Nagar <sharanyanagar@yahoo.in>
Date: Fri, 14 Aug 2026 14:21:19 +0530
Subject: [PATCH 17/19] refactor: apply CSS variable indirection and align
 ThemeToggle skeleton layout

---
 frontend/app/globals.css                   | 203 ++++++++++-----------
 frontend/components/layout/ThemeToggle.tsx |  17 +-
 2 files changed, 115 insertions(+), 105 deletions(-)

diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index 07ae5f7..b651cda 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -33,33 +33,33 @@
 
 @theme {
   /* ── Dynamic Surfaces ─────────────────────────────────────────────────── */
-  --color-bg: var(--color-bg);
-  --color-surface: var(--color-surface);
-  --color-raised: var(--color-raised);
-  --color-overlay: var(--color-overlay);
-  --color-swatch-ground: var(--color-swatch-ground);
+  --color-bg: var(--theme-color-bg);
+  --color-surface: var(--theme-color-surface);
+  --color-raised: var(--theme-color-raised);
+  --color-overlay: var(--theme-color-overlay);
+  --color-swatch-ground: var(--theme-color-swatch-ground);
 
   /* ── Dynamic Text ─────────────────────────────────────────────────────── */
-  --color-text: var(--color-text);
-  --color-text-soft: var(--color-text-soft);
-  --color-text-muted: var(--color-text-muted);
+  --color-text: var(--theme-color-text);
+  --color-text-soft: var(--theme-color-text-soft);
+  --color-text-muted: var(--theme-color-text-muted);
 
   /* ── Dynamic Accent ───────────────────────────────────────────────────── */
-  --color-accent: var(--color-accent);
-  --color-accent-bright: var(--color-accent-bright);
-  --color-accent-vivid: var(--color-accent-vivid);
-  --color-accent-hover: var(--color-accent-hover);
-  --color-accent-dim: var(--color-accent-dim);
+  --color-accent: var(--theme-color-accent);
+  --color-accent-bright: var(--theme-color-accent-bright);
+  --color-accent-vivid: var(--theme-color-accent-vivid);
+  --color-accent-hover: var(--theme-color-accent-hover);
+  --color-accent-dim: var(--theme-color-accent-dim);
   --color-rose: #a8395e;
 
   /* ── Dynamic Status ───────────────────────────────────────────────────── */
-  --color-success: var(--color-success);
-  --color-warn: var(--color-warn);
-  --color-danger: var(--color-danger);
+  --color-success: var(--theme-color-success);
+  --color-warn: var(--theme-color-warn);
+  --color-danger: var(--theme-color-danger);
 
   /* ── Dynamic Lines ────────────────────────────────────────────────────── */
-  --color-line: var(--color-line);
-  --color-line-strong: var(--color-line-strong);
+  --color-line: var(--theme-color-line);
+  --color-line-strong: var(--theme-color-line-strong);
 
   /* ── Type ─────────────────────────────────────────────────────────────── */
   --font-sans: var(--font-inter), system-ui, -apple-system, sans-serif;
@@ -90,9 +90,9 @@
   --radius-pill: 999px;
 
   /* ── Dynamic Elevation ────────────────────────────────────────────────── */
-  --shadow-card: var(--shadow-card);
-  --shadow-lift: var(--shadow-lift);
-  --shadow-glow: var(--shadow-glow);
+  --shadow-card: var(--theme-shadow-card);
+  --shadow-lift: var(--theme-shadow-lift);
+  --shadow-glow: var(--theme-shadow-glow);
 
   /* ── Rhythm ───────────────────────────────────────────────────────────── */
   --space-section: 5rem;
@@ -171,103 +171,102 @@
                       0 24px 48px -20px rgba(0, 0, 0, 0.95);
   --dark-shadow-glow: 0 0 0 1px rgba(198, 134, 66, 0.35),
                       0 16px 40px -20px rgba(198, 134, 66, 0.45);
-
-  /* ── Dark Theme Defaults & Centralized Selector ────────────────────────── */
 }
 
+/* ── Dark Theme Mapping (Default & Explicit) ────────────────────────────── */
 :root,
 .theme-dark,
 html[data-theme="dark"] {
   color-scheme: dark;
-  --color-bg: var(--dark-color-bg);
-  --color-surface: var(--dark-color-surface);
-  --color-raised: var(--dark-color-raised);
-  --color-overlay: var(--dark-color-overlay);
-  --color-swatch-ground: var(--dark-color-swatch-ground);
-
-  --color-text: var(--dark-color-text);
-  --color-text-soft: var(--dark-color-text-soft);
-  --color-text-muted: var(--dark-color-text-muted);
-
-  --color-accent: var(--dark-color-accent);
-  --color-accent-bright: var(--dark-color-accent-bright);
-  --color-accent-vivid: var(--dark-color-accent-vivid);
-  --color-accent-hover: var(--dark-color-accent-hover);
-  --color-accent-dim: var(--dark-color-accent-dim);
-
-  --color-success: var(--dark-color-success);
-  --color-warn: var(--dark-color-warn);
-  --color-danger: var(--dark-color-danger);
-
-  --color-line: var(--dark-color-line);
-  --color-line-strong: var(--dark-color-line-strong);
-
-  --shadow-card: var(--dark-shadow-card);
-  --shadow-lift: var(--dark-shadow-lift);
-  --shadow-glow: var(--dark-shadow-glow);
+  --theme-color-bg: var(--dark-color-bg);
+  --theme-color-surface: var(--dark-color-surface);
+  --theme-color-raised: var(--dark-color-raised);
+  --theme-color-overlay: var(--dark-color-overlay);
+  --theme-color-swatch-ground: var(--dark-color-swatch-ground);
+
+  --theme-color-text: var(--dark-color-text);
+  --theme-color-text-soft: var(--dark-color-text-soft);
+  --theme-color-text-muted: var(--dark-color-text-muted);
+
+  --theme-color-accent: var(--dark-color-accent);
+  --theme-color-accent-bright: var(--dark-color-accent-bright);
+  --theme-color-accent-vivid: var(--dark-color-accent-vivid);
+  --theme-color-accent-hover: var(--dark-color-accent-hover);
+  --theme-color-accent-dim: var(--dark-color-accent-dim);
+
+  --theme-color-success: var(--dark-color-success);
+  --theme-color-warn: var(--dark-color-warn);
+  --theme-color-danger: var(--dark-color-danger);
+
+  --theme-color-line: var(--dark-color-line);
+  --theme-color-line-strong: var(--dark-color-line-strong);
+
+  --theme-shadow-card: var(--dark-shadow-card);
+  --theme-shadow-lift: var(--dark-shadow-lift);
+  --theme-shadow-glow: var(--dark-shadow-glow);
 }
 
-/* Shared Light Theme Token Rule */
+/* ── Light Theme Mapping ───────────────────────────────────────────────── */
 .theme-light,
 html[data-theme="light"] {
   color-scheme: light;
-  --color-bg: var(--light-color-bg);
-  --color-surface: var(--light-color-surface);
-  --color-raised: var(--light-color-raised);
-  --color-overlay: var(--light-color-overlay);
-  --color-swatch-ground: var(--light-color-swatch-ground);
-
-  --color-text: var(--light-color-text);
-  --color-text-soft: var(--light-color-text-soft);
-  --color-text-muted: var(--light-color-text-muted);
-
-  --color-accent: var(--light-color-accent);
-  --color-accent-bright: var(--light-color-accent-bright);
-  --color-accent-vivid: var(--light-color-accent-vivid);
-  --color-accent-hover: var(--light-color-accent-hover);
-  --color-accent-dim: var(--light-color-accent-dim);
-
-  --color-success: var(--light-color-success);
-  --color-warn: var(--light-color-warn);
-  --color-danger: var(--light-color-danger);
-
-  --color-line: var(--light-color-line);
-  --color-line-strong: var(--light-color-line-strong);
-
-  --shadow-card: var(--light-shadow-card);
-  --shadow-lift: var(--light-shadow-lift);
-  --shadow-glow: var(--light-shadow-glow);
+  --theme-color-bg: var(--light-color-bg);
+  --theme-color-surface: var(--light-color-surface);
+  --theme-color-raised: var(--light-color-raised);
+  --theme-color-overlay: var(--light-color-overlay);
+  --theme-color-swatch-ground: var(--light-color-swatch-ground);
+
+  --theme-color-text: var(--light-color-text);
+  --theme-color-text-soft: var(--light-color-text-soft);
+  --theme-color-text-muted: var(--light-color-text-muted);
+
+  --theme-color-accent: var(--light-color-accent);
+  --theme-color-accent-bright: var(--light-color-accent-bright);
+  --theme-color-accent-vivid: var(--light-color-accent-vivid);
+  --theme-color-accent-hover: var(--light-color-accent-hover);
+  --theme-color-accent-dim: var(--light-color-accent-dim);
+
+  --theme-color-success: var(--light-color-success);
+  --theme-color-warn: var(--light-color-warn);
+  --theme-color-danger: var(--light-color-danger);
+
+  --theme-color-line: var(--light-color-line);
+  --theme-color-line-strong: var(--light-color-line-strong);
+
+  --theme-shadow-card: var(--light-shadow-card);
+  --theme-shadow-lift: var(--light-shadow-lift);
+  --theme-shadow-glow: var(--light-shadow-glow);
 }
 
 @media (prefers-color-scheme: light) {
   :root:not([data-theme="dark"]) {
     color-scheme: light;
-    --color-bg: var(--light-color-bg);
-    --color-surface: var(--light-color-surface);
-    --color-raised: var(--light-color-raised);
-    --color-overlay: var(--light-color-overlay);
-    --color-swatch-ground: var(--light-color-swatch-ground);
-
-    --color-text: var(--light-color-text);
-    --color-text-soft: var(--light-color-text-soft);
-    --color-text-muted: var(--light-color-text-muted);
-
-    --color-accent: var(--light-color-accent);
-    --color-accent-bright: var(--light-color-accent-bright);
-    --color-accent-vivid: var(--light-color-accent-vivid);
-    --color-accent-hover: var(--light-color-accent-hover);
-    --color-accent-dim: var(--light-color-accent-dim);
-
-    --color-success: var(--light-color-success);
-    --color-warn: var(--light-color-warn);
-    --color-danger: var(--light-color-danger);
-
-    --color-line: var(--light-color-line);
-    --color-line-strong: var(--light-color-line-strong);
-
-    --shadow-card: var(--light-shadow-card);
-    --shadow-lift: var(--light-shadow-lift);
-    --shadow-glow: var(--light-shadow-glow);
+    --theme-color-bg: var(--light-color-bg);
+    --theme-color-surface: var(--light-color-surface);
+    --theme-color-raised: var(--light-color-raised);
+    --theme-color-overlay: var(--light-color-overlay);
+    --theme-color-swatch-ground: var(--light-color-swatch-ground);
+
+    --theme-color-text: var(--light-color-text);
+    --theme-color-text-soft: var(--light-color-text-soft);
+    --theme-color-text-muted: var(--light-color-text-muted);
+
+    --theme-color-accent: var(--light-color-accent);
+    --theme-color-accent-bright: var(--light-color-accent-bright);
+    --theme-color-accent-vivid: var(--light-color-accent-vivid);
+    --theme-color-accent-hover: var(--light-color-accent-hover);
+    --theme-color-accent-dim: var(--light-color-accent-dim);
+
+    --theme-color-success: var(--light-color-success);
+    --theme-color-warn: var(--light-color-warn);
+    --theme-color-danger: var(--light-color-danger);
+
+    --theme-color-line: var(--light-color-line);
+    --theme-color-line-strong: var(--light-color-line-strong);
+
+    --theme-shadow-card: var(--light-shadow-card);
+    --theme-shadow-lift: var(--light-shadow-lift);
+    --theme-shadow-glow: var(--light-shadow-glow);
   }
 }
 
diff --git a/frontend/components/layout/ThemeToggle.tsx b/frontend/components/layout/ThemeToggle.tsx
index 7e98e8b..b190237 100644
--- a/frontend/components/layout/ThemeToggle.tsx
+++ b/frontend/components/layout/ThemeToggle.tsx
@@ -54,13 +54,24 @@ export function ThemeToggle({ className }: { className?: string }) {
     return (
       <div
         className={cn(
-          "inline-flex h-9 items-center gap-1.5 rounded-pill border border-line bg-raised/50 px-2.5 py-1",
+          "inline-flex h-9 items-center gap-1.5 rounded-pill border border-line bg-raised/60 px-2.5 py-1",
+          "text-small font-medium text-text-soft transition-colors duration-[var(--duration-fast)]",
           className,
         )}
         aria-hidden="true"
       >
-        <div className="h-4 w-4 rounded-full bg-text-muted/20" />
-        <div className="hidden sm:inline-block h-3 w-8 rounded bg-text-muted/20" />
+        <svg
+          className="h-4 w-4 text-text-muted/40"
+          fill="none"
+          viewBox="0 0 24 24"
+          stroke="currentColor"
+          strokeWidth={2}
+          aria-hidden="true"
+        >
+          <rect x="3" y="4" width="18" height="12" rx="2" />
+          <path strokeLinecap="round" d="M8 20h8m-4-4v4" />
+        </svg>
+        <span className="hidden sm:inline text-xs text-text-muted/40">Auto</span>
       </div>
     );
   }

From bd7931ea14e62bfe5aa79501949ecf7eb16e3133 Mon Sep 17 00:00:00 2001
From: Sharanya Nagar <sharanyanagar@yahoo.in>
Date: Fri, 14 Aug 2026 14:24:36 +0530
Subject: [PATCH 18/19] refactor: centralize theme resolution helpers, extract
 system theme listener, and add meta tag creation guard

---
 frontend/components/layout/ThemeToggle.tsx | 15 ++-----
 frontend/lib/theme.ts                      | 47 ++++++++++++++++++++--
 2 files changed, 46 insertions(+), 16 deletions(-)

diff --git a/frontend/components/layout/ThemeToggle.tsx b/frontend/components/layout/ThemeToggle.tsx
index b190237..6ceba2e 100644
--- a/frontend/components/layout/ThemeToggle.tsx
+++ b/frontend/components/layout/ThemeToggle.tsx
@@ -6,6 +6,7 @@ import {
   ThemeMode,
   getStoredTheme,
   applyTheme,
+  subscribeToSystemTheme,
 } from "@/lib/theme";
 
 export function ThemeToggle({ className }: { className?: string }) {
@@ -22,21 +23,11 @@ export function ThemeToggle({ className }: { className?: string }) {
     setTheme(stored);
     applyTheme(stored);
 
-    const mediaQuery = window.matchMedia("(prefers-color-scheme: light)");
-    const handleChange = () => {
+    return subscribeToSystemTheme(() => {
       if (themeRef.current === "system") {
         applyTheme("system");
       }
-    };
-
-    if ("addEventListener" in mediaQuery) {
-      mediaQuery.addEventListener("change", handleChange);
-      return () => mediaQuery.removeEventListener("change", handleChange);
-    } else {
-      // Fallback for older browsers (e.g. Safari < 14)
-      (mediaQuery as MediaQueryList).addListener(handleChange);
-      return () => (mediaQuery as MediaQueryList).removeListener(handleChange);
-    }
+    });
   }, []);
 
   const updateThemeMode = (nextTheme: ThemeMode) => {
diff --git a/frontend/lib/theme.ts b/frontend/lib/theme.ts
index d424cb2..d55e454 100644
--- a/frontend/lib/theme.ts
+++ b/frontend/lib/theme.ts
@@ -58,6 +58,7 @@ export function getStoredTheme(): ThemeMode | null {
 /**
  * Updates the <meta name="theme-color"> header content based on active theme
  * and system preference, caching the DOM reference for performance.
+ * Dynamically creates and appends the meta tag to document.head if missing.
  */
 export function updateMetaThemeColor(theme: ThemeMode): void {
   if (typeof window === "undefined") return;
@@ -65,6 +66,11 @@ export function updateMetaThemeColor(theme: ThemeMode): void {
   if (!cachedMetaTag || !document.contains(cachedMetaTag)) {
     cachedMetaTag = document.querySelector('meta[name="theme-color"]') as HTMLMetaElement | null;
   }
+  if (!cachedMetaTag && document.head) {
+    cachedMetaTag = document.createElement("meta");
+    cachedMetaTag.setAttribute("name", "theme-color");
+    document.head.appendChild(cachedMetaTag);
+  }
   if (!cachedMetaTag) return;
 
   const prefersLight = window.matchMedia("(prefers-color-scheme: light)").matches;
@@ -96,23 +102,56 @@ export function applyTheme(theme: ThemeMode): void {
   updateMetaThemeColor(theme);
 }
 
+/**
+ * Subscribes to OS system color scheme changes ("prefers-color-scheme: light").
+ * Executes the provided callback whenever the system color scheme changes.
+ * Returns an unsubscribe cleanup function.
+ */
+export function subscribeToSystemTheme(onChange: () => void): () => void {
+  if (typeof window === "undefined" || !window.matchMedia) {
+    return () => {};
+  }
+
+  const mediaQuery = window.matchMedia("(prefers-color-scheme: light)");
+  const handleChange = () => onChange();
+
+  if ("addEventListener" in mediaQuery) {
+    mediaQuery.addEventListener("change", handleChange);
+    return () => mediaQuery.removeEventListener("change", handleChange);
+  } else {
+    // Fallback for older browsers (e.g. Safari < 14)
+    (mediaQuery as MediaQueryList).addListener(handleChange);
+    return () => (mediaQuery as MediaQueryList).removeListener(handleChange);
+  }
+}
+
 /**
  * Pre-hydration inline script string injected into <head> via next/script beforeInteractive.
- * Written as a self-contained inline script string to avoid brittleness under bundler minification.
+ * Reuses stringified getThemeAttribute and isLightTheme decision helpers to avoid drift.
+ * Dynamically creates meta[name="theme-color"] if missing in <head>.
  */
 export const THEME_PRELOAD_SCRIPT = `(function() {
   try {
+    var getThemeAttribute = ${getThemeAttribute.toString()};
+    var isLightTheme = ${isLightTheme.toString()};
+
     var stored = localStorage.getItem("${THEME_STORAGE_KEY}");
     var root = document.documentElement;
-    if (stored === "light" || stored === "dark") {
-      root.setAttribute("data-theme", stored);
+    var attr = getThemeAttribute(stored);
+    if (attr) {
+      root.setAttribute("data-theme", attr);
     } else {
       root.removeAttribute("data-theme");
     }
 
     var prefersLight = window.matchMedia("(prefers-color-scheme: light)").matches;
-    var isLight = stored === "light" || ((!stored || stored === "system") && prefersLight);
+    var isLight = isLightTheme(stored, prefersLight);
     var meta = document.querySelector('meta[name="theme-color"]');
+    if (!meta && document.head) {
+      meta = document.createElement('meta');
+      meta.setAttribute('name', 'theme-color');
+      document.head.appendChild(meta);
+    }
     if (meta) {
       meta.setAttribute("content", isLight ? "${THEME_COLOR_LIGHT}" : "${THEME_COLOR_DARK}");
     }

From 2aadc9f4659ee2543ae58b2fc54edf526fc71e92 Mon Sep 17 00:00:00 2001
From: Sharanya Nagar <sharanyanagar@yahoo.in>
Date: Fri, 14 Aug 2026 14:31:42 +0530
Subject: [PATCH 19/19] refactor: inline script literal in THEME_PRELOAD_SCRIPT
 and optimize beforeInteractive script placement in layout

---
 frontend/app/layout.tsx |  4 +---
 frontend/lib/theme.ts   | 14 +++++---------
 2 files changed, 6 insertions(+), 12 deletions(-)

diff --git a/frontend/app/layout.tsx b/frontend/app/layout.tsx
index 86835a6..48120eb 100644
--- a/frontend/app/layout.tsx
+++ b/frontend/app/layout.tsx
@@ -38,7 +38,7 @@ export default function RootLayout({
   return (
     {/* suppressHydrationWarning is placed on <html> strictly for the data-theme attribute injected pre-hydration by THEME_PRELOAD_SCRIPT. React only suppresses attribute warnings on <html> itself. */}
     <html lang="en" className={`${inter.variable} ${fraunces.variable}`} suppressHydrationWarning>
-      <head>
+      <body className="min-h-screen bg-bg text-text antialiased">
         <Script
           id="theme-preload"
           strategy="beforeInteractive"
@@ -46,8 +46,6 @@ export default function RootLayout({
             __html: THEME_PRELOAD_SCRIPT,
           }}
         />
-      </head>
-      <body className="min-h-screen bg-bg text-text antialiased">
         {/* First thing in the tab order — keyboard users shouldn't have to
             traverse the nav on every page. */}
         <a href="#main" className="sr-only-focusable">
diff --git a/frontend/lib/theme.ts b/frontend/lib/theme.ts
index d55e454..5ae3dcb 100644
--- a/frontend/lib/theme.ts
+++ b/frontend/lib/theme.ts
@@ -126,26 +126,22 @@ export function subscribeToSystemTheme(onChange: () => void): () => void {
 }
 
 /**
- * Pre-hydration inline script string injected into <head> via next/script beforeInteractive.
- * Reuses stringified getThemeAttribute and isLightTheme decision helpers to avoid drift.
+ * Pre-hydration inline script string injected via next/script beforeInteractive.
+ * Written as a self-contained inline script string to avoid function serialization issues during minification.
  * Dynamically creates meta[name="theme-color"] if missing in <head>.
  */
 export const THEME_PRELOAD_SCRIPT = `(function() {
   try {
-    var getThemeAttribute = ${getThemeAttribute.toString()};
-    var isLightTheme = ${isLightTheme.toString()};
-
     var stored = localStorage.getItem("${THEME_STORAGE_KEY}");
     var root = document.documentElement;
-    var attr = getThemeAttribute(stored);
-    if (attr) {
-      root.setAttribute("data-theme", attr);
+    if (stored === "light" || stored === "dark") {
+      root.setAttribute("data-theme", stored);
     } else {
       root.removeAttribute("data-theme");
     }
 
     var prefersLight = window.matchMedia("(prefers-color-scheme: light)").matches;
-    var isLight = isLightTheme(stored, prefersLight);
+    var isLight = stored === "light" || ((!stored || stored === "system") && prefersLight);
     var meta = document.querySelector('meta[name="theme-color"]');
     if (!meta && document.head) {
       meta = document.createElement('meta');