feat: add light/dark theme toggle with warm cream light mode

Kosthi · claude · Kosthi · commit 7332127bfca5 · 2026-02-07T01:21:42.000+08:00
Implement a complete theme system with dark/light mode switching:

- Create theme-tokens.css as single source of truth for all theme colors
- Add FOUC prevention script in BaseLayout head for instant theme load
- Add theme toggle button (sun/moon icons) to NavBar desktop and mobile
- Replace 50+ hardcoded dark rgba values in global.css with CSS variables
- Add comprehensive [data-theme="light"] overrides for all components:
  panel, section, cards, timeline, lightbox, footer, prose code blocks,
  hero title, contact QR codes, social links, etc.
- Support multi-tab sync via storage event and window.__rushdbTheme API
- Light palette uses warm cream (#fdf6e3) with brown-toned text/borders
- Use mix-blend-mode: multiply for QR images to blend with cream bg
- Add i18n strings for theme toggle in zh/en/ja

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/src/components/blog/PostCard.astro b/src/components/blog/PostCard.astro
@@ -79,8 +79,8 @@ const heroImage = post.data.heroImage;
 
 <style>
   .post-card {
-    background: rgba(10, 14, 32, 0.62);
-    border: 1px solid rgba(240, 246, 255, 0.12);
+    background: var(--surface);
+    border: 1px solid var(--line);
     border-radius: 18px;
     transition: all 0.4s cubic-bezier(0.16, 1, 0.3, 1);
     overflow: hidden;
diff --git a/src/components/blog/RelatedPosts.astro b/src/components/blog/RelatedPosts.astro
@@ -115,7 +115,7 @@ function formatDate(date: Date): string {
   .related-posts {
     margin-top: 4rem;
     padding-top: 3rem;
-    border-top: 1px solid rgba(240, 246, 255, 0.1);
+    border-top: 1px solid var(--line);
   }
 
   .related-posts-title {
@@ -149,8 +149,8 @@ function formatDate(date: Date): string {
     display: flex;
     flex-direction: column;
     padding: 1.25rem;
-    background: rgba(10, 14, 32, 0.5);
-    border: 1px solid rgba(240, 246, 255, 0.1);
+    background: var(--surface);
+    border: 1px solid var(--line);
     border-radius: 14px;
     text-decoration: none;
     transition: all 0.4s cubic-bezier(0.16, 1, 0.3, 1);
diff --git a/src/components/blog/TableOfContents.astro b/src/components/blog/TableOfContents.astro
@@ -140,8 +140,8 @@ const filteredHeadings = headings.filter(h => h.depth <= 3);
   .toc {
     position: sticky;
     top: 100px;
-    background: rgba(10, 14, 32, 0.62);
-    border: 1px solid rgba(240, 246, 255, 0.12);
+    background: var(--surface);
+    border: 1px solid var(--line);
     border-radius: 14px;
     padding: 1.25rem;
     backdrop-filter: blur(12px);
@@ -155,7 +155,7 @@ const filteredHeadings = headings.filter(h => h.depth <= 3);
     text-transform: uppercase;
     letter-spacing: 0.05em;
     padding-bottom: 0.75rem;
-    border-bottom: 1px solid rgba(240, 246, 255, 0.1);
+    border-bottom: 1px solid var(--line);
   }
 
   .toc-list {
@@ -209,7 +209,7 @@ const filteredHeadings = headings.filter(h => h.depth <= 3);
     width: 6px;
     height: 6px;
     border-radius: 50%;
-    background: rgba(240, 246, 255, 0.2);
+    background: var(--line);
     flex-shrink: 0;
     transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1);
   }
diff --git a/src/components/vue/NavBar.vue b/src/components/vue/NavBar.vue
@@ -23,8 +23,9 @@ const t = (key: string) => {
 
 const isLanguageOpen = ref(false);
 const isMenuOpen = ref(false);
-const navbarBg = ref('rgba(5, 7, 18, 0.72)');
+const isScrolled = ref(false);
 const activeSection = ref('');
+const theme = ref<'dark' | 'light'>('dark');
 
 const languageLabel = computed(() => t(`language.${props.lang}`));
 
@@ -106,7 +107,32 @@ function onLogoClick(event: MouseEvent) {
 }
 
 function updateNavbarBg() {
-  navbarBg.value = window.scrollY > 100 ? 'rgba(5, 7, 18, 0.82)' : 'rgba(5, 7, 18, 0.72)';
+  isScrolled.value = window.scrollY > 100;
+}
+
+function toggleTheme() {
+  const w = window as any;
+  if (w.__rushdbTheme) {
+    w.__rushdbTheme.toggle();
+  }
+}
+
+function syncThemeState() {
+  const current = document.documentElement.getAttribute('data-theme') || 'dark';
+  theme.value = current as 'dark' | 'light';
+}
+
+function onThemeChange() {
+  syncThemeState();
+}
+
+function onStorageChange(e: StorageEvent) {
+  if (e.key !== 'rushdb-theme') return;
+  const w = window as any;
+  if (w.__rushdbTheme && e.newValue) {
+    w.__rushdbTheme.set(e.newValue, false);
+  }
+  syncThemeState();
 }
 
 function onKeydown(e: KeyboardEvent) {
@@ -174,15 +200,20 @@ function setupNavHighlightObserver() {
 }
 
 onMounted(() => {
+  syncThemeState();
   updateNavbarBg();
   window.addEventListener('scroll', updateNavbarBg, { passive: true });
+  window.addEventListener('rushdb-theme-change', onThemeChange);
+  window.addEventListener('storage', onStorageChange);
   document.addEventListener('keydown', onKeydown);
   document.addEventListener('click', onDocumentClick);
   setupNavHighlightObserver();
 });
 
 onUnmounted(() => {
   window.removeEventListener('scroll', updateNavbarBg);
+  window.removeEventListener('rushdb-theme-change', onThemeChange);
+  window.removeEventListener('storage', onStorageChange);
   document.removeEventListener('keydown', onKeydown);
   document.removeEventListener('click', onDocumentClick);
   navHighlightObserver?.disconnect();
@@ -191,7 +222,7 @@ onUnmounted(() => {
 </script>
 
 <template>
-  <nav class="navbar" :class="{ 'menu-open': isMenuOpen }" :style="{ background: navbarBg }" role="navigation" :aria-label="t('a11y.mainNavigation')">
+  <nav class="navbar" :class="{ 'menu-open': isMenuOpen, 'is-scrolled': isScrolled }" role="navigation" :aria-label="t('a11y.mainNavigation')">
     <div class="nav-content">
       <a :href="homePath" class="nav-logo" @click="onLogoClick">
         <img src="/RushDB.png" alt="RushDB Logo" class="nav-logo-img" />
@@ -224,6 +255,20 @@ onUnmounted(() => {
           </li>
         </ul>
 
+        <button
+          class="theme-toggle"
+          type="button"
+          :aria-label="theme === 'dark' ? t('nav.switchToLight') : t('nav.switchToDark')"
+          @click="toggleTheme"
+        >
+          <svg v-if="theme === 'dark'" class="theme-toggle-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <path d="M12 3v1m0 16v1m9-9h-1M4 12H3m15.364 6.364l-.707-.707M6.343 6.343l-.707-.707m12.728 0l-.707.707M6.343 17.657l-.707.707M16 12a4 4 0 11-8 0 4 4 0 018 0z" />
+          </svg>
+          <svg v-else class="theme-toggle-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <path 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>
+        </button>
+
         <div class="language-switcher" :class="{ show: isLanguageOpen }">
           <div class="language-trigger" @click="toggleLanguageSwitcher">{{ languageLabel }}</div>
           <div class="language-dropdown">
@@ -294,6 +339,19 @@ onUnmounted(() => {
         </ul>
 
         <div class="nav-mobile-actions">
+          <button
+            class="theme-toggle"
+            type="button"
+            :aria-label="theme === 'dark' ? t('nav.switchToLight') : t('nav.switchToDark')"
+            @click="toggleTheme"
+          >
+            <svg v-if="theme === 'dark'" class="theme-toggle-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <path d="M12 3v1m0 16v1m9-9h-1M4 12H3m15.364 6.364l-.707-.707M6.343 6.343l-.707-.707m12.728 0l-.707.707M6.343 17.657l-.707.707M16 12a4 4 0 11-8 0 4 4 0 018 0z" />
+            </svg>
+            <svg v-else class="theme-toggle-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <path 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>
+          </button>
           <div class="language-switcher mobile-lang" :class="{ show: isLanguageOpen }">
             <div class="language-trigger" @click="toggleLanguageSwitcher">{{ languageLabel }}</div>
             <div class="language-dropdown">
diff --git a/src/i18n/ui.ts b/src/i18n/ui.ts
@@ -20,6 +20,8 @@ export const ui = {
       blog: '博客',
       github: 'View Our Github',
       openMenu: '打开菜单',
+      switchToLight: '切换到浅色模式',
+      switchToDark: '切换到深色模式',
     },
     hero: {
       title: 'RushDB 无限进步',
@@ -226,6 +228,8 @@ export const ui = {
       blog: 'Blog',
       github: 'View Our Github',
       openMenu: 'Open menu',
+      switchToLight: 'Switch to Light Mode',
+      switchToDark: 'Switch to Dark Mode',
     },
     hero: {
       title: 'RushDB, Unlimited Progress',
@@ -432,6 +436,8 @@ export const ui = {
       blog: 'ブログ',
       github: 'View Our Github',
       openMenu: 'メニューを開く',
+      switchToLight: 'ライトモードに切替',
+      switchToDark: 'ダークモードに切替',
     },
     hero: {
       title: 'RushDB、無限の進歩',
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
@@ -58,6 +58,8 @@ const metaDescription = description || descriptions[lang];
     <link rel="icon" type="image/png" href="/RushDB.png" />
     <link rel="shortcut icon" type="image/png" href="/RushDB.png" />
     <link rel="apple-touch-icon" href="/RushDB.png" />
+    <meta name="theme-color" content="#050712" media="(prefers-color-scheme: dark)" />
+    <meta name="theme-color" content="#fdf6e3" media="(prefers-color-scheme: light)" />
     <link
       href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=Source+Serif+4:ital,opsz,wght@0,8..60,200..900;1,8..60,200..900&display=swap"
       rel="stylesheet"
@@ -85,6 +87,61 @@ const metaDescription = description || descriptions[lang];
     <link rel="alternate" hreflang="en" href="https://rushdb-lab.github.io/en/" />
     <link rel="alternate" hreflang="ja" href="https://rushdb-lab.github.io/ja/" />
     <link rel="alternate" hreflang="x-default" href="https://rushdb-lab.github.io/zh/" />
+
+    <!-- Theme initialization (FOUC prevention - must run before first paint) -->
+    <script is:inline>
+      (function() {
+        var KEY = 'rushdb-theme';
+        var ALLOWED = { dark: 1, light: 1 };
+        var root = document.documentElement;
+
+        function sanitize(v) { return typeof v === 'string' && ALLOWED[v] ? v : null; }
+        function readStorage() { try { return sanitize(localStorage.getItem(KEY)); } catch(e) { return null; } }
+
+        var media = window.matchMedia('(prefers-color-scheme: dark)');
+        var systemTheme = media.matches ? 'dark' : 'light';
+        var stored = readStorage();
+        var resolved = stored || systemTheme;
+
+        root.setAttribute('data-theme', resolved);
+        root.style.colorScheme = resolved;
+        root.setAttribute('data-theme-source', stored ? 'user' : 'system');
+        root.classList.add('theme-preload');
+
+        window.__rushdbTheme = {
+          get: function() { return root.getAttribute('data-theme') || 'dark'; },
+          set: function(next, persist) {
+            var safe = sanitize(next);
+            if (!safe) return;
+            root.setAttribute('data-theme', safe);
+            root.style.colorScheme = safe;
+            root.setAttribute('data-theme-source', persist !== false ? 'user' : 'system');
+            try {
+              if (persist !== false) localStorage.setItem(KEY, safe);
+              else localStorage.removeItem(KEY);
+            } catch(e) {}
+            window.dispatchEvent(new CustomEvent('rushdb-theme-change', { detail: { theme: safe } }));
+          },
+          toggle: function() {
+            var current = root.getAttribute('data-theme') || 'dark';
+            this.set(current === 'dark' ? 'light' : 'dark', true);
+          }
+        };
+
+        var onMediaChange = function(e) {
+          if (root.getAttribute('data-theme-source') === 'user') return;
+          var t = e.matches ? 'dark' : 'light';
+          root.setAttribute('data-theme', t);
+          root.style.colorScheme = t;
+          window.dispatchEvent(new CustomEvent('rushdb-theme-change', { detail: { theme: t } }));
+        };
+        if (media.addEventListener) {
+          media.addEventListener('change', onMediaChange);
+        } else if (media.addListener) {
+          media.addListener(onMediaChange);
+        }
+      })();
+    </script>
   </head>
   <body>
     <a href="#main-content" class="skip-link">{t('a11y.skipToContent')}</a>
@@ -222,6 +279,7 @@ const metaDescription = description || descriptions[lang];
       }, { passive: true });
 
       document.addEventListener('DOMContentLoaded', () => {
+        requestAnimationFrame(() => document.documentElement.classList.remove('theme-preload'));
         updateScrollProgress();
         setupMousePositionEffect();
         setupSectionObserver();
diff --git a/src/pages/[lang]/blog/[slug].astro b/src/pages/[lang]/blog/[slug].astro
@@ -160,8 +160,8 @@ const formattedDate = post.data.pubDate.toLocaleDateString(
   }
 
   .post-content {
-    background: rgba(10, 14, 32, 0.62);
-    border: 1px solid rgba(240, 246, 255, 0.12);
+    background: var(--surface);
+    border: 1px solid var(--line);
     border-radius: 18px;
     padding: 2rem;
   }
@@ -177,7 +177,7 @@ const formattedDate = post.data.pubDate.toLocaleDateString(
 
   .post-content :global(h2) {
     font-size: 1.5rem;
-    border-bottom: 1px solid rgba(240, 246, 255, 0.1);
+    border-bottom: 1px solid var(--line);
     padding-bottom: 0.5rem;
   }
 
@@ -199,15 +199,15 @@ const formattedDate = post.data.pubDate.toLocaleDateString(
   }
 
   .post-content :global(code) {
-    background: rgba(240, 246, 255, 0.08);
+    background: var(--line-2, rgba(240, 246, 255, 0.08));
     padding: 0.2rem 0.4rem;
     border-radius: 4px;
     font-size: 0.9em;
   }
 
   .post-content :global(pre) {
-    background: rgba(10, 14, 32, 0.9) !important;
-    border: 1px solid rgba(240, 246, 255, 0.1);
+    background: var(--bg-primary) !important;
+    border: 1px solid var(--line);
     border-radius: 12px;
     padding: 1rem;
     overflow-x: auto;
@@ -227,13 +227,13 @@ const formattedDate = post.data.pubDate.toLocaleDateString(
 
   .post-content :global(th),
   .post-content :global(td) {
-    border: 1px solid rgba(240, 246, 255, 0.1);
+    border: 1px solid var(--line);
     padding: 0.75rem;
     text-align: left;
   }
 
   .post-content :global(th) {
-    background: rgba(240, 246, 255, 0.05);
+    background: var(--line-2, rgba(240, 246, 255, 0.05));
     color: var(--text);
   }
 
diff --git a/src/styles/global.css b/src/styles/global.css
diff --git a/src/styles/theme-tokens.css b/src/styles/theme-tokens.css
