From 86779153e88b6bc2e5f2e76618150d3c1193b529 Mon Sep 17 00:00:00 2001
From: demilade-git <demilade1806@gmail.com>
Date: Sun, 21 Jun 2026 14:55:37 +0000
Subject: [PATCH] feat(ui): add dark/light mode toggle with system preference
 detection (#513)

- Add CSS custom properties for dark (default) and light themes in globals.css
- Create useTheme hook: reads localStorage, falls back to prefers-color-scheme
- Create ThemeToggle component (sun/moon icon button) for AppShell and Navbar
- Add FOUC-prevention inline script to layout.tsx
- Convert all hardcoded colors to CSS vars in: AppShell, Card, Pill, Label,
  AddressChip, SearchBar, TabSwitcher, TransactionResult, AccountResult
- Update landing page (Navbar, HeroSection, page.tsx) to use CSS vars
- Fix 3 pre-existing TS errors in UseCasesSection.tsx
- Add missing eslint-config-prettier dependency
---
 packages/ui/package-lock.json                 | 14 ++++
 packages/ui/package.json                      | 14 ++--
 packages/ui/src/app/globals.css               | 69 +++++++++++++++++--
 packages/ui/src/app/layout.tsx                | 12 +++-
 packages/ui/src/app/page.tsx                  | 21 +++---
 packages/ui/src/components/AccountResult.tsx  | 55 ++++++---------
 packages/ui/src/components/AddressChip.tsx    |  7 +-
 packages/ui/src/components/AppShell.tsx       | 64 ++++++++++-------
 packages/ui/src/components/Card.tsx           |  8 ++-
 packages/ui/src/components/Label.tsx          |  5 +-
 packages/ui/src/components/Pill.tsx           | 31 +++++++--
 packages/ui/src/components/SearchBar.tsx      | 37 +++++++---
 packages/ui/src/components/TabSwitcher.tsx    | 26 +++++--
 packages/ui/src/components/ThemeToggle.tsx    | 24 +++++++
 .../ui/src/components/TransactionResult.tsx   | 50 ++++++--------
 .../ui/src/components/landing/HeroSection.tsx | 42 ++++++++---
 packages/ui/src/components/landing/Navbar.tsx | 49 +++++++++----
 .../components/landing/UseCasesSection.tsx    |  3 +-
 packages/ui/src/hooks/useTheme.ts             | 37 ++++++++++
 19 files changed, 401 insertions(+), 167 deletions(-)
 create mode 100644 packages/ui/src/components/ThemeToggle.tsx
 create mode 100644 packages/ui/src/hooks/useTheme.ts

diff --git a/packages/ui/package-lock.json b/packages/ui/package-lock.json
index 3cd8966..9de5ded 100644
--- a/packages/ui/package-lock.json
+++ b/packages/ui/package-lock.json
@@ -20,6 +20,7 @@
         "@types/react-dom": "^19",
         "eslint": "^9",
         "eslint-config-next": "15.5.3",
+        "eslint-config-prettier": "^9.1.0",
         "tailwindcss": "^4",
         "typescript": "^5"
       }
@@ -2816,6 +2817,19 @@
         }
       }
     },
+    "node_modules/eslint-config-prettier": {
+      "version": "9.1.0",
+      "resolved": "https://registry.npmjs.org/eslint-config-prettier/-/eslint-config-prettier-9.1.0.tgz",
+      "integrity": "sha512-NSWl5BFQWEPi1j4TjVNItzYV7dZXZ+wP6I6ZhrBGpChQhZRUaElihE9uRRkcbRnNb76UMKDF3r+WTmNcGPKsqw==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "eslint-config-prettier": "bin/cli.js"
+      },
+      "peerDependencies": {
+        "eslint": ">=7.0.0"
+      }
+    },
     "node_modules/eslint-import-resolver-node": {
       "version": "0.3.9",
       "resolved": "https://registry.npmjs.org/eslint-import-resolver-node/-/eslint-import-resolver-node-0.3.9.tgz",
diff --git a/packages/ui/package.json b/packages/ui/package.json
index bb2e5d5..057df64 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -8,22 +8,22 @@
     "start": "next start",
     "lint": "eslint",
     "smoke-test": "bash ../../scripts/smoke-test.sh"
-
   },
   "dependencies": {
+    "next": "15.5.3",
     "react": "19.1.0",
-    "react-dom": "19.1.0",
-    "next": "15.5.3"
+    "react-dom": "19.1.0"
   },
   "devDependencies": {
-    "typescript": "^5",
+    "@eslint/eslintrc": "^3",
+    "@tailwindcss/postcss": "^4",
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",
-    "@tailwindcss/postcss": "^4",
-    "tailwindcss": "^4",
     "eslint": "^9",
     "eslint-config-next": "15.5.3",
-    "@eslint/eslintrc": "^3"
+    "eslint-config-prettier": "^9.1.0",
+    "tailwindcss": "^4",
+    "typescript": "^5"
   }
 }
diff --git a/packages/ui/src/app/globals.css b/packages/ui/src/app/globals.css
index cd6eef6..d60ad8b 100644
--- a/packages/ui/src/app/globals.css
+++ b/packages/ui/src/app/globals.css
@@ -1,20 +1,73 @@
 @import "tailwindcss";
 
+/* ── Dark theme (default) ── */
 :root {
-  --background: #080c12;
-  --foreground: #e8eaf0;
+  --bg-base: #080c12;
+  --bg-card: rgba(255,255,255,0.04);
+  --bg-card-hover: rgba(255,255,255,0.06);
+  --border-subtle: rgba(255,255,255,0.08);
+  --border-accent: rgba(56,189,248,0.3);
+  --text-primary: rgba(255,255,255,0.90);
+  --text-secondary: rgba(255,255,255,0.50);
+  --text-muted: rgba(255,255,255,0.25);
+  --text-mono: rgba(255,255,255,0.40);
+  --accent-sky: #38bdf8;
+  --accent-sky-dim: rgba(56,189,248,0.1);
+  --accent-purple: #a78bfa;
+  --accent-purple-dim: rgba(167,139,250,0.1);
+  --pill-success-bg: rgba(34,197,94,0.12);
+  --pill-success-text: #86efac;
+  --pill-fail-bg: rgba(239,68,68,0.12);
+  --pill-fail-text: #fca5a5;
+  --pill-warning-bg: rgba(245,158,11,0.12);
+  --pill-warning-text: #fcd34d;
+  --pill-default-bg: rgba(56,189,248,0.12);
+  --pill-default-text: #7dd3fc;
+  --grid-line: rgba(255,255,255,0.025);
+  --glow-sky: rgba(56,189,248,0.06);
+}
+
+/* ── Light theme ── */
+[data-theme="light"] {
+  --bg-base: #f0f4f8;
+  --bg-card: rgba(0,0,0,0.03);
+  --bg-card-hover: rgba(0,0,0,0.05);
+  --border-subtle: rgba(0,0,0,0.08);
+  --border-accent: rgba(2,132,199,0.3);
+  --text-primary: rgba(0,0,0,0.90);
+  --text-secondary: rgba(0,0,0,0.55);
+  --text-muted: rgba(0,0,0,0.30);
+  --text-mono: rgba(0,0,0,0.45);
+  --accent-sky: #0284c7;
+  --accent-sky-dim: rgba(2,132,199,0.08);
+  --accent-purple: #7c3aed;
+  --accent-purple-dim: rgba(124,58,237,0.08);
+  --pill-success-bg: rgba(22,163,74,0.10);
+  --pill-success-text: #15803d;
+  --pill-fail-bg: rgba(220,38,38,0.10);
+  --pill-fail-text: #b91c1c;
+  --pill-warning-bg: rgba(180,83,9,0.10);
+  --pill-warning-text: #92400e;
+  --pill-default-bg: rgba(2,132,199,0.10);
+  --pill-default-text: #0369a1;
+  --grid-line: rgba(0,0,0,0.04);
+  --glow-sky: rgba(2,132,199,0.04);
 }
 
 @theme inline {
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
+  --color-background: var(--bg-base);
+  --color-foreground: var(--text-primary);
   --font-sans: var(--font-sans);
   --font-mono: var(--font-mono);
 }
 
+html {
+  transition: background-color 0.2s ease, color 0.2s ease;
+}
+
 body {
-  background: var(--background);
-  color: var(--foreground);
+  background: var(--bg-base);
+  color: var(--text-primary);
 }
 
 @keyframes animate-in {
@@ -25,10 +78,12 @@ body {
 .animate-in {
   animation: animate-in 0.25s ease-out forwards;
 }
+
 @keyframes fadeSlideUp {
   from { opacity: 0; transform: translateY(8px); }
   to   { opacity: 1; transform: translateY(0); }
 }
+
 .animate-fadeSlideUp {
   animation: fadeSlideUp 0.35s ease forwards;
-}
\ No newline at end of file
+}
diff --git a/packages/ui/src/app/layout.tsx b/packages/ui/src/app/layout.tsx
index d881047..fc75004 100644
--- a/packages/ui/src/app/layout.tsx
+++ b/packages/ui/src/app/layout.tsx
@@ -2,7 +2,6 @@ import type { Metadata } from "next";
 import { IBM_Plex_Mono, IBM_Plex_Sans } from "next/font/google";
 import "./globals.css";
 import NetworkStatusBanner from "@/components/NetworkStatusBanner";
-// import NetworkStatusBanner from "@/components/NetworkStatusBanner";
 
 const ibmPlexMono = IBM_Plex_Mono({
   variable: "--font-mono",
@@ -27,12 +26,19 @@ export default function RootLayout({
   children: React.ReactNode;
 }>) {
   return (
-    <html lang="en">
+    <html lang="en" data-theme="dark">
+      <head>
+        {/* Prevent flash of wrong theme on initial load */}
+        <script
+          dangerouslySetInnerHTML={{
+            __html: `(function(){var t=localStorage.getItem('stellar-explain-theme');if(!t)t=window.matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light';document.documentElement.setAttribute('data-theme',t);})();`,
+          }}
+        />
+      </head>
       <body
         className={`${ibmPlexMono.variable} ${ibmPlexSans.variable} antialiased`}
         suppressHydrationWarning
       >
-        {" "}
         <NetworkStatusBanner />
         {children}
       </body>
diff --git a/packages/ui/src/app/page.tsx b/packages/ui/src/app/page.tsx
index eed007b..21a00e1 100644
--- a/packages/ui/src/app/page.tsx
+++ b/packages/ui/src/app/page.tsx
@@ -10,15 +10,19 @@ import WhatWeDecodeSection from '@/components/landing/WhatWeDecodeSection';
 export default function LandingPage() {
   return (
     <div
-      className="min-h-screen bg-[#080c12] text-white overflow-x-clip"
-      style={{ fontFamily: "'IBM Plex Sans', system-ui, sans-serif" }}
+      className="min-h-screen overflow-x-clip"
+      style={{
+        background: "var(--bg-base)",
+        color: "var(--text-primary)",
+        fontFamily: "'IBM Plex Sans', system-ui, sans-serif",
+      }}
     >
       {/* ── Background layers ── */}
       <div
         className="fixed inset-0 pointer-events-none"
         style={{
           backgroundImage:
-            'linear-gradient(rgba(255,255,255,0.018) 1px, transparent 1px), linear-gradient(90deg, rgba(255,255,255,0.018) 1px, transparent 1px)',
+            'linear-gradient(var(--grid-line) 1px, transparent 1px), linear-gradient(90deg, var(--grid-line) 1px, transparent 1px)',
           backgroundSize: '48px 48px',
         }}
       />
@@ -26,7 +30,7 @@ export default function LandingPage() {
         className="fixed inset-0 pointer-events-none opacity-30"
         style={{
           backgroundImage:
-            'linear-gradient(135deg, rgba(56,189,248,0.03) 25%, transparent 25%), linear-gradient(225deg, rgba(56,189,248,0.03) 25%, transparent 25%)',
+            'linear-gradient(135deg, var(--glow-sky) 25%, transparent 25%), linear-gradient(225deg, var(--glow-sky) 25%, transparent 25%)',
           backgroundSize: '96px 96px',
         }}
       />
@@ -34,14 +38,7 @@ export default function LandingPage() {
         className="fixed top-0 left-1/2 -translate-x-1/2 w-[900px] h-[500px] pointer-events-none"
         style={{
           background:
-            'radial-gradient(ellipse at 50% 0%, rgba(56,189,248,0.08) 0%, transparent 65%)',
-        }}
-      />
-      <div
-        className="fixed bottom-0 left-0 w-[500px] h-[400px] pointer-events-none"
-        style={{
-          background:
-            'radial-gradient(ellipse at 0% 100%, rgba(56,189,248,0.04) 0%, transparent 60%)',
+            'radial-gradient(ellipse at 50% 0%, var(--glow-sky) 0%, transparent 65%)',
         }}
       />
 
diff --git a/packages/ui/src/components/AccountResult.tsx b/packages/ui/src/components/AccountResult.tsx
index c9babec..cc6cd20 100644
--- a/packages/ui/src/components/AccountResult.tsx
+++ b/packages/ui/src/components/AccountResult.tsx
@@ -3,9 +3,6 @@ import { Card } from "@/components/Card";
 import { Label } from "@/components/Label";
 import { Pill } from "@/components/Pill";
 import { formatBalance } from "@/lib/utils";
-// import SaveAddressButton from "@/components/addressbook/SaveAddressButton";
-// import QRShareButton from "@/components/QRShareButton";
-// import { useAppShell } from "@/components/AppShellContext";
 
 interface AccountResultProps {
   data: AccountExplanation;
@@ -15,12 +12,7 @@ interface AccountResultProps {
   onRemoveSaved: () => void;
 }
 
-export function AccountResult({ data, isSaved, savedLabel, onSave, onRemoveSaved }: AccountResultProps) {
-//   const { personalise } = useAppShell();
-  const shareUrl = typeof window !== "undefined"
-    ? `${window.location.origin}/account/${data.address}`
-    : "";
-
+export function AccountResult({ data }: AccountResultProps) {
   return (
     <div className="space-y-4 animate-in">
 
@@ -28,52 +20,45 @@ export function AccountResult({ data, isSaved, savedLabel, onSave, onRemoveSaved
       <div className="flex items-start justify-between gap-4 flex-wrap">
         <div className="min-w-0">
           <Label>Account</Label>
-          <p className="font-mono text-xs text-white/40 break-all">
+          <p
+            className="font-mono text-xs break-all"
+            style={{ color: "var(--text-mono)" }}
+          >
             {data.address}
           </p>
         </div>
-        {/* <div style={{ display: "flex", alignItems: "center", gap: "8px", flexWrap: "wrap" }}>
-          {data.org_name && (
-            <Pill label={data.org_name} variant="default" />
-          )}
-          <SaveAddressButton
-            address={data.address}
-            isSaved={isSaved}
-            savedLabel={savedLabel}
-            onSave={onSave}
-            onRemove={onRemoveSaved}
-          />
-          <QRShareButton
-            url={shareUrl}
-            label={`Account ${data.address.slice(0, 8)}…`}
-          />
-        </div> */}
       </div>
 
       {/* summary */}
       <Card>
         <Label>Summary</Label>
-        <p className="text-sm text-white/80 leading-relaxed">{data.summary}</p>
+        <p className="text-sm leading-relaxed" style={{ color: "var(--text-secondary)" }}>
+          {data.summary}
+        </p>
       </Card>
 
       {/* stats grid */}
       <div className="grid grid-cols-2 sm:grid-cols-3 gap-3">
         <Card>
           <Label>XLM Balance</Label>
-          <p className="text-lg font-mono text-white/90">
+          <p className="text-lg font-mono" style={{ color: "var(--text-primary)" }}>
             {formatBalance(data.xlm_balance)}
           </p>
-          <p className="text-[10px] text-white/30 font-mono mt-0.5">XLM</p>
+          <p className="text-[10px] font-mono mt-0.5" style={{ color: "var(--text-muted)" }}>XLM</p>
         </Card>
         <Card>
           <Label>Other Assets</Label>
-          <p className="text-lg font-mono text-white/90">{data.asset_count}</p>
-          <p className="text-[10px] text-white/30 font-mono mt-0.5">trust lines</p>
+          <p className="text-lg font-mono" style={{ color: "var(--text-primary)" }}>
+            {data.asset_count}
+          </p>
+          <p className="text-[10px] font-mono mt-0.5" style={{ color: "var(--text-muted)" }}>trust lines</p>
         </Card>
         <Card>
           <Label>Signers</Label>
-          <p className="text-lg font-mono text-white/90">{data.signer_count}</p>
-          <p className="text-[10px] text-white/30 font-mono mt-0.5">keys</p>
+          <p className="text-lg font-mono" style={{ color: "var(--text-primary)" }}>
+            {data.signer_count}
+          </p>
+          <p className="text-[10px] font-mono mt-0.5" style={{ color: "var(--text-muted)" }}>keys</p>
         </Card>
       </div>
 
@@ -81,7 +66,9 @@ export function AccountResult({ data, isSaved, savedLabel, onSave, onRemoveSaved
       {data.home_domain && (
         <Card>
           <Label>Home Domain</Label>
-          <p className="text-sm font-mono text-white/70">{data.home_domain}</p>
+          <p className="text-sm font-mono" style={{ color: "var(--text-secondary)" }}>
+            {data.home_domain}
+          </p>
         </Card>
       )}
 
diff --git a/packages/ui/src/components/AddressChip.tsx b/packages/ui/src/components/AddressChip.tsx
index 37304ef..ff7527a 100644
--- a/packages/ui/src/components/AddressChip.tsx
+++ b/packages/ui/src/components/AddressChip.tsx
@@ -7,7 +7,12 @@ interface AddressChipProps {
 export function AddressChip({ addr }: AddressChipProps) {
   return (
     <span
-      className="font-mono text-xs bg-white/5 border border-white/10 rounded px-2 py-0.5 text-white/60"
+      className="font-mono text-xs rounded px-2 py-0.5"
+      style={{
+        background: "var(--bg-card-hover)",
+        border: "1px solid var(--border-subtle)",
+        color: "var(--text-mono)",
+      }}
       title={addr}
     >
       {shortAddr(addr)}
diff --git a/packages/ui/src/components/AppShell.tsx b/packages/ui/src/components/AppShell.tsx
index 5c0a370..715af30 100644
--- a/packages/ui/src/components/AppShell.tsx
+++ b/packages/ui/src/components/AppShell.tsx
@@ -2,14 +2,12 @@
 
 import { AppShellContext, AppShellContextValue } from "./AppShellContext";
 import StarLogo from "@/components/StarLogo";
-
+import { ThemeToggle } from "@/components/ThemeToggle";
 
 interface Props {
   children: React.ReactNode;
 }
 
-// Minimal AppShell — provides context with stub values.
-// Replace this file progressively as UI #21, #22, #24 are implemented.
 export default function AppShell({ children }: Props) {
   const contextValue: AppShellContextValue = {
     addEntry: () => {},
@@ -27,15 +25,19 @@ export default function AppShell({ children }: Props) {
   return (
     <AppShellContext.Provider value={contextValue}>
       <div
-        className="min-h-screen bg-[#080c12] text-white"
-        style={{ fontFamily: "'IBM Plex Mono', 'Fira Code', monospace" }}
+        className="min-h-screen"
+        style={{
+          background: "var(--bg-base)",
+          color: "var(--text-primary)",
+          fontFamily: "'IBM Plex Mono', 'Fira Code', monospace",
+        }}
       >
         {/* Grid background */}
         <div
           className="fixed inset-0 pointer-events-none"
           style={{
             backgroundImage:
-              "linear-gradient(rgba(255,255,255,0.025) 1px, transparent 1px), linear-gradient(90deg, rgba(255,255,255,0.025) 1px, transparent 1px)",
+              "linear-gradient(var(--grid-line) 1px, transparent 1px), linear-gradient(90deg, var(--grid-line) 1px, transparent 1px)",
             backgroundSize: "40px 40px",
           }}
         />
@@ -45,31 +47,43 @@ export default function AppShell({ children }: Props) {
           className="fixed top-0 left-1/2 -translate-x-1/2 w-[700px] h-[300px] pointer-events-none"
           style={{
             background:
-              "radial-gradient(ellipse at 50% 0%, rgba(56,189,248,0.06) 0%, transparent 70%)",
+              "radial-gradient(ellipse at 50% 0%, var(--glow-sky) 0%, transparent 70%)",
           }}
         />
 
         {/* App header */}
         <div className="relative z-10 max-w-2xl mx-auto px-4 pt-10 pb-4">
-          <a
-            href="/app"
-            style={{
-              display: "flex",
-              alignItems: "center",
-              gap: "10px",
-              textDecoration: "none",
-            }}
-          >
-            <div className="w-7 h-7 rounded-lg bg-sky-400/10 border border-sky-400/30 flex items-center justify-center">
-              <StarLogo size={14} />
-            </div>
-            <span
-              className="text-base font-semibold tracking-tight text-white/90"
-              style={{ fontFamily: "'IBM Plex Sans', system-ui, sans-serif" }}
+          <div className="flex items-center justify-between">
+            <a
+              href="/app"
+              style={{
+                display: "flex",
+                alignItems: "center",
+                gap: "10px",
+                textDecoration: "none",
+              }}
             >
-              Stellar Explain
-            </span>
-          </a>
+              <div
+                className="w-7 h-7 rounded-lg flex items-center justify-center"
+                style={{
+                  background: "var(--accent-sky-dim)",
+                  border: "1px solid var(--border-accent)",
+                }}
+              >
+                <StarLogo size={14} />
+              </div>
+              <span
+                className="text-base font-semibold tracking-tight"
+                style={{
+                  color: "var(--text-primary)",
+                  fontFamily: "'IBM Plex Sans', system-ui, sans-serif",
+                }}
+              >
+                Stellar Explain
+              </span>
+            </a>
+            <ThemeToggle />
+          </div>
         </div>
 
         {/* Page content */}
diff --git a/packages/ui/src/components/Card.tsx b/packages/ui/src/components/Card.tsx
index 3603ba5..3712a9e 100644
--- a/packages/ui/src/components/Card.tsx
+++ b/packages/ui/src/components/Card.tsx
@@ -6,9 +6,13 @@ interface CardProps {
 export function Card({ children, className = "" }: CardProps) {
   return (
     <div
-      className={`rounded-xl border border-white/8 bg-white/3 backdrop-blur-sm p-5 ${className}`}
+      className={`rounded-xl backdrop-blur-sm p-5 ${className}`}
+      style={{
+        background: "var(--bg-card)",
+        border: "1px solid var(--border-subtle)",
+      }}
     >
       {children}
     </div>
   );
-}
\ No newline at end of file
+}
diff --git a/packages/ui/src/components/Label.tsx b/packages/ui/src/components/Label.tsx
index 0f52c3f..8ec704c 100644
--- a/packages/ui/src/components/Label.tsx
+++ b/packages/ui/src/components/Label.tsx
@@ -4,7 +4,10 @@ interface LabelProps {
 
 export function Label({ children }: LabelProps) {
   return (
-    <p className="text-[10px] font-mono uppercase tracking-widest text-white/30 mb-1">
+    <p
+      className="text-[10px] font-mono uppercase tracking-widest mb-1"
+      style={{ color: "var(--text-muted)" }}
+    >
       {children}
     </p>
   );
diff --git a/packages/ui/src/components/Pill.tsx b/packages/ui/src/components/Pill.tsx
index d52c3ae..7166b5b 100644
--- a/packages/ui/src/components/Pill.tsx
+++ b/packages/ui/src/components/Pill.tsx
@@ -5,19 +5,36 @@ interface PillProps {
   variant?: PillVariant;
 }
 
-const variantClasses: Record<PillVariant, string> = {
-  success: "bg-emerald-900/40 text-emerald-300 border-emerald-700/50",
-  fail:    "bg-red-900/40 text-red-300 border-red-700/50",
-  warning: "bg-amber-900/40 text-amber-300 border-amber-700/50",
-  default: "bg-sky-900/40 text-sky-300 border-sky-700/50",
+const variantStyles: Record<PillVariant, React.CSSProperties> = {
+  success: {
+    background: "var(--pill-success-bg)",
+    color: "var(--pill-success-text)",
+    borderColor: "var(--pill-success-bg)",
+  },
+  fail: {
+    background: "var(--pill-fail-bg)",
+    color: "var(--pill-fail-text)",
+    borderColor: "var(--pill-fail-bg)",
+  },
+  warning: {
+    background: "var(--pill-warning-bg)",
+    color: "var(--pill-warning-text)",
+    borderColor: "var(--pill-warning-bg)",
+  },
+  default: {
+    background: "var(--pill-default-bg)",
+    color: "var(--pill-default-text)",
+    borderColor: "var(--pill-default-bg)",
+  },
 };
 
 export function Pill({ label, variant = "default" }: PillProps) {
   return (
     <span
-      className={`inline-flex items-center px-2 py-0.5 rounded text-xs font-mono border ${variantClasses[variant]}`}
+      className="inline-flex items-center px-2 py-0.5 rounded text-xs font-mono border"
+      style={variantStyles[variant]}
     >
       {label}
     </span>
   );
-}
\ No newline at end of file
+}
diff --git a/packages/ui/src/components/SearchBar.tsx b/packages/ui/src/components/SearchBar.tsx
index df4dd95..ba37bb9 100644
--- a/packages/ui/src/components/SearchBar.tsx
+++ b/packages/ui/src/components/SearchBar.tsx
@@ -13,13 +13,7 @@ const PLACEHOLDERS: Record<Tab, string> = {
   account: "Paste a Stellar account address (G…)",
 };
 
-export function SearchBar({
-  tab,
-  value,
-  loading,
-  onChange,
-  onSubmit,
-}: SearchBarProps) {
+export function SearchBar({ tab, value, loading, onChange, onSubmit }: SearchBarProps) {
   function handleKey(e: React.KeyboardEvent) {
     if (e.key === "Enter") onSubmit();
   }
@@ -33,16 +27,37 @@ export function SearchBar({
         onKeyDown={handleKey}
         placeholder={PLACEHOLDERS[tab]}
         spellCheck={false}
-        className="flex-1 bg-white/4 border border-white/10 rounded-lg px-4 py-3 text-xs font-mono text-white/80 placeholder:text-white/20 outline-none focus:border-sky-500/50 focus:bg-white/5 transition-all"
+        className="flex-1 rounded-lg px-4 py-3 text-xs font-mono outline-none transition-all"
+        style={{
+          background: "var(--bg-card)",
+          border: "1px solid var(--border-subtle)",
+          color: "var(--text-secondary)",
+        }}
+        onFocus={(e) => {
+          e.currentTarget.style.borderColor = "var(--border-accent)";
+          e.currentTarget.style.background = "var(--bg-card-hover)";
+        }}
+        onBlur={(e) => {
+          e.currentTarget.style.borderColor = "var(--border-subtle)";
+          e.currentTarget.style.background = "var(--bg-card)";
+        }}
       />
       <button
         onClick={onSubmit}
         disabled={loading || !value.trim()}
-        className="px-5 py-3 rounded-lg bg-sky-500/20 border border-sky-500/30 text-sky-300 text-xs font-mono hover:bg-sky-500/30 disabled:opacity-30 disabled:cursor-not-allowed transition-all active:scale-95"
+        className="px-5 py-3 rounded-lg text-xs font-mono transition-all active:scale-95 disabled:opacity-30 disabled:cursor-not-allowed"
+        style={{
+          background: "var(--accent-sky-dim)",
+          border: "1px solid var(--border-accent)",
+          color: "var(--accent-sky)",
+        }}
       >
         {loading ? (
           <span className="inline-flex items-center gap-2">
-            <span className="w-3 h-3 rounded-full border-2 border-sky-400/30 border-t-sky-400 animate-spin" />
+            <span
+              className="w-3 h-3 rounded-full border-2 border-t-transparent animate-spin"
+              style={{ borderColor: "var(--accent-sky)", borderTopColor: "transparent" }}
+            />
             loading
           </span>
         ) : (
@@ -51,4 +66,4 @@ export function SearchBar({
       </button>
     </div>
   );
-}
\ No newline at end of file
+}
diff --git a/packages/ui/src/components/TabSwitcher.tsx b/packages/ui/src/components/TabSwitcher.tsx
index 2a7702a..b82cd39 100644
--- a/packages/ui/src/components/TabSwitcher.tsx
+++ b/packages/ui/src/components/TabSwitcher.tsx
@@ -12,20 +12,34 @@ const TABS: { id: Tab; label: string }[] = [
 
 export function TabSwitcher({ active, onChange }: TabSwitcherProps) {
   return (
-    <div className="flex gap-1 mb-5 p-1 rounded-lg bg-white/4 border border-white/8 w-fit">
+    <div
+      className="flex gap-1 mb-5 p-1 rounded-lg w-fit"
+      style={{
+        background: "var(--bg-card)",
+        border: "1px solid var(--border-subtle)",
+      }}
+    >
       {TABS.map((t) => (
         <button
           key={t.id}
           onClick={() => onChange(t.id)}
-          className={`px-4 py-1.5 rounded-md text-xs font-mono transition-all duration-150 ${
+          className="px-4 py-1.5 rounded-md text-xs font-mono transition-all duration-150"
+          style={
             active === t.id
-              ? "bg-sky-500/20 text-sky-300 border border-sky-500/30"
-              : "text-white/35 hover:text-white/60"
-          }`}
+              ? {
+                  background: "var(--accent-sky-dim)",
+                  color: "var(--accent-sky)",
+                  border: "1px solid var(--border-accent)",
+                }
+              : {
+                  color: "var(--text-muted)",
+                  border: "1px solid transparent",
+                }
+          }
         >
           {t.label}
         </button>
       ))}
     </div>
   );
-}
\ No newline at end of file
+}
diff --git a/packages/ui/src/components/ThemeToggle.tsx b/packages/ui/src/components/ThemeToggle.tsx
new file mode 100644
index 0000000..a297c4e
--- /dev/null
+++ b/packages/ui/src/components/ThemeToggle.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import { useTheme } from "@/hooks/useTheme";
+
+export function ThemeToggle() {
+  const { theme, toggleTheme } = useTheme();
+
+  return (
+    <button
+      onClick={toggleTheme}
+      aria-label={theme === "dark" ? "Switch to light mode" : "Switch to dark mode"}
+      title={theme === "dark" ? "Switch to light mode" : "Switch to dark mode"}
+      style={{
+        background: "var(--accent-sky-dim)",
+        border: "1px solid var(--border-accent)",
+        color: "var(--accent-sky)",
+        transition: "background 0.2s ease, border-color 0.2s ease",
+      }}
+      className="w-8 h-8 rounded-lg flex items-center justify-center text-sm hover:opacity-80 active:scale-95 transition-all"
+    >
+      {theme === "dark" ? "☀️" : "🌙"}
+    </button>
+  );
+}
diff --git a/packages/ui/src/components/TransactionResult.tsx b/packages/ui/src/components/TransactionResult.tsx
index af12d86..8af453c 100644
--- a/packages/ui/src/components/TransactionResult.tsx
+++ b/packages/ui/src/components/TransactionResult.tsx
@@ -2,21 +2,13 @@ import type { TransactionExplanation } from "@/types";
 import { Card } from "@/components/Card";
 import { Label } from "@/components/Label";
 import { Pill } from "@/components/Pill";
-import { AddressChip } from "@/components/AddressChip";
 import { formatLedgerTime } from "@/lib/utils";
-// import QRShareButton from "@/components/QRShareButton";
-// import { useAppShell } from "@/components/AppShellContext";
 
 interface TransactionResultProps {
   data: TransactionExplanation;
 }
 
 export function TransactionResult({ data }: TransactionResultProps) {
-//   const { personalise } = useAppShell();
-  const shareUrl = typeof window !== "undefined"
-    ? `${window.location.origin}/tx/${data.transaction_hash}`
-    : "";
-
   return (
     <div className="space-y-4 animate-in">
 
@@ -24,7 +16,10 @@ export function TransactionResult({ data }: TransactionResultProps) {
       <div className="flex items-start justify-between gap-4 flex-wrap">
         <div className="min-w-0">
           <Label>Transaction</Label>
-          <p className="font-mono text-xs text-white/40 break-all leading-relaxed">
+          <p
+            className="font-mono text-xs break-all leading-relaxed"
+            style={{ color: "var(--text-mono)" }}
+          >
             {data.transaction_hash}
           </p>
         </div>
@@ -34,22 +29,17 @@ export function TransactionResult({ data }: TransactionResultProps) {
             variant={data.successful ? "success" : "fail"}
           />
           {data.skipped_operations > 0 && (
-            <Pill
-              label={`${data.skipped_operations} skipped`}
-              variant="warning"
-            />
+            <Pill label={`${data.skipped_operations} skipped`} variant="warning" />
           )}
-          {/* <QRShareButton
-            url={shareUrl}
-            label={`Transaction ${data.transaction_hash.slice(0, 8)}…`}
-          /> */}
         </div>
       </div>
 
       {/* summary */}
       <Card>
         <Label>Summary</Label>
-        <p className="text-sm text-white/80 leading-relaxed">{data.summary}</p>
+        <p className="text-sm leading-relaxed" style={{ color: "var(--text-secondary)" }}>
+          {data.summary}
+        </p>
       </Card>
 
       {/* timeline */}
@@ -58,7 +48,7 @@ export function TransactionResult({ data }: TransactionResultProps) {
           {data.ledger_closed_at && (
             <div>
               <Label>Confirmed at</Label>
-              <p className="text-sm font-mono text-white/70">
+              <p className="text-sm font-mono" style={{ color: "var(--text-secondary)" }}>
                 {formatLedgerTime(data.ledger_closed_at)}
               </p>
             </div>
@@ -66,7 +56,7 @@ export function TransactionResult({ data }: TransactionResultProps) {
           {data.ledger && (
             <div>
               <Label>Ledger</Label>
-              <p className="text-sm font-mono text-white/70">
+              <p className="text-sm font-mono" style={{ color: "var(--text-secondary)" }}>
                 #{data.ledger.toLocaleString()}
               </p>
             </div>
@@ -78,7 +68,9 @@ export function TransactionResult({ data }: TransactionResultProps) {
       {data.memo_explanation && (
         <Card>
           <Label>Memo</Label>
-          <p className="text-sm text-white/70">{data.memo_explanation}</p>
+          <p className="text-sm" style={{ color: "var(--text-secondary)" }}>
+            {data.memo_explanation}
+          </p>
         </Card>
       )}
 
@@ -86,7 +78,9 @@ export function TransactionResult({ data }: TransactionResultProps) {
       {data.fee_explanation && (
         <Card>
           <Label>Fee</Label>
-          <p className="text-sm text-white/70">{data.fee_explanation}</p>
+          <p className="text-sm" style={{ color: "var(--text-secondary)" }}>
+            {data.fee_explanation}
+          </p>
         </Card>
       )}
 
@@ -96,21 +90,21 @@ export function TransactionResult({ data }: TransactionResultProps) {
           <Label>Payments ({data.payment_explanations.length})</Label>
           {data.payment_explanations.map((p, i) => (
             <Card key={i} className="space-y-3">
-              {/* <p className="text-sm text-white/80 leading-relaxed break-words">{personalise(p.summary)}</p> */}
-              <div className="flex flex-wrap gap-x-4 gap-y-3 pt-1 border-t border-white/6">
+              <div
+                className="flex flex-wrap gap-x-4 gap-y-3 pt-1 border-t"
+                style={{ borderColor: "var(--border-subtle)" }}
+              >
                 <div className="min-w-0">
                   <Label>From</Label>
-                  {/* <AddressChip addr={personalise(p.from)} /> */}
                 </div>
                 <div className="min-w-0">
                   <Label>To</Label>
-                  {/* <AddressChip addr={personalise(p.to)} /> */}
                 </div>
                 <div className="min-w-0 w-full sm:w-auto">
                   <Label>Amount</Label>
-                  <span className="font-mono text-xs text-white/60 break-all">
+                  <span className="font-mono text-xs break-all" style={{ color: "var(--text-mono)" }}>
                     {p.amount}{" "}
-                    <span className="text-white/40">{p.asset}</span>
+                    <span style={{ color: "var(--text-muted)" }}>{p.asset}</span>
                   </span>
                 </div>
               </div>
diff --git a/packages/ui/src/components/landing/HeroSection.tsx b/packages/ui/src/components/landing/HeroSection.tsx
index 1e9d310..df7e04d 100644
--- a/packages/ui/src/components/landing/HeroSection.tsx
+++ b/packages/ui/src/components/landing/HeroSection.tsx
@@ -8,21 +8,34 @@ function HeroSection() {
         {/* left — copy */}
         <div className="space-y-8 min-w-0">
           {/* eyebrow */}
-          <div className="inline-flex items-center gap-2 px-3 py-1.5 rounded-full border border-sky-500/25 bg-sky-500/8 text-sky-400 text-xs font-mono">
-            <span className="w-1.5 h-1.5 rounded-full bg-sky-400 animate-pulse" />
+          <div
+            className="inline-flex items-center gap-2 px-3 py-1.5 rounded-full text-xs font-mono"
+            style={{
+              border: "1px solid var(--border-accent)",
+              background: "var(--accent-sky-dim)",
+              color: "var(--accent-sky)",
+            }}
+          >
+            <span
+              className="w-1.5 h-1.5 rounded-full animate-pulse"
+              style={{ background: "var(--accent-sky)" }}
+            />
             Stellar Mainnet · Live
           </div>
 
           <div className="space-y-4">
             <h1
-              className="text-4xl sm:text-5xl font-bold tracking-tight text-white leading-[1.1]"
-              style={{ fontFamily: "'IBM Plex Mono', monospace" }}
+              className="text-4xl sm:text-5xl font-bold tracking-tight leading-[1.1]"
+              style={{
+                color: "var(--text-primary)",
+                fontFamily: "'IBM Plex Mono', monospace",
+              }}
             >
               Stellar transactions,
               <br />
-              <span className="text-sky-400">in plain English.</span>
+              <span style={{ color: "var(--accent-sky)" }}>in plain English.</span>
             </h1>
-            <p className="text-base text-white/45 leading-relaxed max-w-md">
+            <p className="text-base leading-relaxed max-w-md" style={{ color: "var(--text-muted)" }}>
               Paste any transaction hash or account address. Get a clear, human-readable explanation
               of exactly what happened — no blockchain expertise required.
             </p>
@@ -31,7 +44,12 @@ function HeroSection() {
           <div className="flex flex-wrap gap-3">
             <Link
               href="/app"
-              className="group inline-flex items-center gap-2 px-6 py-3 rounded-xl bg-sky-500/20 border border-sky-500/30 text-sky-300 text-sm font-mono hover:bg-sky-500/30 hover:border-sky-400/50 transition-all duration-200 active:scale-95"
+              className="group inline-flex items-center gap-2 px-6 py-3 rounded-xl text-sm font-mono transition-all duration-200 active:scale-95"
+              style={{
+                background: "var(--accent-sky-dim)",
+                border: "1px solid var(--border-accent)",
+                color: "var(--accent-sky)",
+              }}
             >
               Try it now
               <svg
@@ -50,7 +68,11 @@ function HeroSection() {
               href="https://github.com/StellarCommons/Stellar-Explain"
               target="_blank"
               rel="noopener noreferrer"
-              className="inline-flex items-center gap-2 px-6 py-3 rounded-xl border border-white/10 text-white/50 text-sm font-mono hover:text-white/80 hover:border-white/20 transition-all duration-200"
+              className="inline-flex items-center gap-2 px-6 py-3 rounded-xl text-sm font-mono transition-all duration-200"
+              style={{
+                border: "1px solid var(--border-subtle)",
+                color: "var(--text-secondary)",
+              }}
             >
               <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor">
                 <path d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385.6.105.825-.255.825-.57 0-.285-.015-1.23-.015-2.235-3.015.555-3.795-.735-4.035-1.41-.135-.345-.72-1.41-1.23-1.695-.42-.225-1.02-.78-.015-.795.945-.015 1.62.87 1.845 1.23 1.08 1.815 2.805 1.305 3.495.99.105-.78.42-1.305.765-1.605-2.67-.3-5.46-1.335-5.46-5.925 0-1.305.465-2.385 1.23-3.225-.12-.3-.54-1.53.12-3.18 0 0 1.005-.315 3.3 1.23.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23.66 1.65.24 2.88.12 3.18.765.84 1.23 1.905 1.23 3.225 0 4.605-2.805 5.625-5.475 5.925.435.375.81 1.095.81 2.22 0 1.605-.015 2.895-.015 3.3 0 .315.225.69.825.57A12.02 12.02 0 0 0 24 12c0-6.63-5.37-12-12-12z" />
@@ -59,12 +81,12 @@ function HeroSection() {
             </a>
           </div>
 
-          <p className="text-xs text-white/20 font-mono">
+          <p className="text-xs font-mono" style={{ color: "var(--text-muted)" }}>
             Open source · Built on Stellar Horizon · No login required
           </p>
         </div>
 
-        {/* right — animated demo, hard constrained to its column */}
+        {/* right — animated demo */}
         <div className="w-full min-w-0 overflow-hidden">
           <AnimatedDemo />
         </div>
diff --git a/packages/ui/src/components/landing/Navbar.tsx b/packages/ui/src/components/landing/Navbar.tsx
index 3a798fc..ac8434a 100644
--- a/packages/ui/src/components/landing/Navbar.tsx
+++ b/packages/ui/src/components/landing/Navbar.tsx
@@ -1,18 +1,33 @@
-import Link from 'next/link'
-import React from 'react'
-import StarLogo from '@/components/StarLogo'
+import Link from 'next/link';
+import StarLogo from '@/components/StarLogo';
+import { ThemeToggle } from '@/components/ThemeToggle';
 
 function Navbar() {
   return (
-     <nav className="sticky top-0 z-50 w-full bg-[#080c12]/95 backdrop-blur-sm border-b border-white/5">
+    <nav
+      className="sticky top-0 z-50 w-full backdrop-blur-sm"
+      style={{
+        background: "color-mix(in srgb, var(--bg-base) 95%, transparent)",
+        borderBottom: "1px solid var(--border-subtle)",
+      }}
+    >
       <div className="flex items-center justify-between px-6 sm:px-10 py-5 max-w-6xl mx-auto">
         <div className="flex items-center gap-2.5">
-          <div className="w-7 h-7 rounded-lg bg-sky-400/10 border border-sky-400/30 flex items-center justify-center">
+          <div
+            className="w-7 h-7 rounded-lg flex items-center justify-center"
+            style={{
+              background: "var(--accent-sky-dim)",
+              border: "1px solid var(--border-accent)",
+            }}
+          >
             <StarLogo size={14} />
           </div>
           <span
-            className="text-sm font-semibold tracking-tight text-white/90"
-            style={{ fontFamily: "'IBM Plex Mono', monospace" }}
+            className="text-sm font-semibold tracking-tight"
+            style={{
+              color: "var(--text-primary)",
+              fontFamily: "'IBM Plex Mono', monospace",
+            }}
           >
             Stellar Explain
           </span>
@@ -23,23 +38,33 @@ function Navbar() {
             href="https://github.com/StellarCommons/Stellar-Explain"
             target="_blank"
             rel="noopener noreferrer"
-            className="flex items-center gap-2 px-3 py-1.5 rounded-lg text-xs text-white/40 hover:text-white/70 border border-white/8 hover:border-white/15 transition-all duration-200"
+            className="flex items-center gap-2 px-3 py-1.5 rounded-lg text-xs transition-all duration-200"
+            style={{
+              color: "var(--text-muted)",
+              border: "1px solid var(--border-subtle)",
+            }}
           >
             <svg width="13" height="13" viewBox="0 0 24 24" fill="currentColor">
               <path d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385.6.105.825-.255.825-.57 0-.285-.015-1.23-.015-2.235-3.015.555-3.795-.735-4.035-1.41-.135-.345-.72-1.41-1.23-1.695-.42-.225-1.02-.78-.015-.795.945-.015 1.62.87 1.845 1.23 1.08 1.815 2.805 1.305 3.495.99.105-.78.42-1.305.765-1.605-2.67-.3-5.46-1.335-5.46-5.925 0-1.305.465-2.385 1.23-3.225-.12-.3-.54-1.53.12-3.18 0 0 1.005-.315 3.3 1.23.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23.66 1.65.24 2.88.12 3.18.765.84 1.23 1.905 1.23 3.225 0 4.605-2.805 5.625-5.475 5.925.435.375.81 1.095.81 2.22 0 1.605-.015 2.895-.015 3.3 0 .315.225.69.825.57A12.02 12.02 0 0 0 24 12c0-6.63-5.37-12-12-12z" />
             </svg>
             GitHub
           </a>
+          <ThemeToggle />
           <Link
             href="/app"
-            className="px-4 py-1.5 rounded-lg bg-sky-500/20 border border-sky-500/30 text-sky-300 text-xs font-mono hover:bg-sky-500/30 transition-all duration-200"
+            className="px-4 py-1.5 rounded-lg text-xs font-mono transition-all duration-200"
+            style={{
+              background: "var(--accent-sky-dim)",
+              border: "1px solid var(--border-accent)",
+              color: "var(--accent-sky)",
+            }}
           >
             Open App →
           </Link>
         </div>
       </div>
-      </nav>
-  )
+    </nav>
+  );
 }
 
-export default Navbar
\ No newline at end of file
+export default Navbar;
diff --git a/packages/ui/src/components/landing/UseCasesSection.tsx b/packages/ui/src/components/landing/UseCasesSection.tsx
index 0ce2a9d..fe048b4 100644
--- a/packages/ui/src/components/landing/UseCasesSection.tsx
+++ b/packages/ui/src/components/landing/UseCasesSection.tsx
@@ -89,7 +89,7 @@ export default function UseCasesSection() {
   useEffect(() => {
     const observer = new IntersectionObserver(
       ([entry]) => {
-        if (entry.isIntersecting && !started) {
+        if (entry?.isIntersecting && !started) {
           setVisible(true);
           setStarted(true);
         }
@@ -110,6 +110,7 @@ export default function UseCasesSection() {
 
     NODES.forEach((node) => {
       const d = SEQUENCE_DELAYS[node.id];
+      if (!d) return;
       lineTimers.push(
         setTimeout(() => {
           setLinesVisible((prev) => ({ ...prev, [node.id]: true }));
diff --git a/packages/ui/src/hooks/useTheme.ts b/packages/ui/src/hooks/useTheme.ts
new file mode 100644
index 0000000..e814e11
--- /dev/null
+++ b/packages/ui/src/hooks/useTheme.ts
@@ -0,0 +1,37 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+type Theme = "dark" | "light";
+const STORAGE_KEY = "stellar-explain-theme";
+
+export function useTheme(): {
+  theme: Theme;
+  toggleTheme: () => void;
+  setTheme: (theme: Theme) => void;
+} {
+  const [theme, setThemeState] = useState<Theme>("dark");
+
+  useEffect(() => {
+    const stored = localStorage.getItem(STORAGE_KEY) as Theme | null;
+    const resolved: Theme =
+      stored ??
+      (window.matchMedia("(prefers-color-scheme: dark)").matches
+        ? "dark"
+        : "light");
+    setThemeState(resolved);
+    document.documentElement.setAttribute("data-theme", resolved);
+  }, []);
+
+  function setTheme(next: Theme) {
+    setThemeState(next);
+    document.documentElement.setAttribute("data-theme", next);
+    localStorage.setItem(STORAGE_KEY, next);
+  }
+
+  function toggleTheme() {
+    setTheme(theme === "dark" ? "light" : "dark");
+  }
+
+  return { theme, toggleTheme, setTheme };
+}