color mode switching

src/app.html

@@ -10,9 +10,26 @@
     <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
     <link rel="manifest" href="/manifest.json" crossorigin="use-credentials" />
 
-    <!-- Static CSS imports to ensure theme is always available -->
+    <!-- All theme CSS files loaded statically - data-theme attribute controls which applies -->
+    <link rel="stylesheet" href="/light-theme.css" />
+    <link rel="stylesheet" href="/dark-theme.css" />
     <link rel="stylesheet" href="/system-theme.css" />
 
+    <!-- Blocking script to prevent theme flash - must run before page renders -->
+    <script>
+      ;(function () {
+        var theme = localStorage.getItem('color-mode') || 'system'
+        document.documentElement.setAttribute('data-theme', theme)
+        if (
+          theme === 'dark' ||
+          (theme === 'system' &&
+            window.matchMedia('(prefers-color-scheme: dark)').matches)
+        ) {
+          document.documentElement.classList.add('dark')
+        }
+      })()
+    </script>
+
     <!-- required for triggering custom events in signup form -->
     <script>
       window.plausible =

src/lib/components/ui/ThemeSwitcher.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
-  import { colorMode } from '../../stores'
+  import { onMount } from 'svelte'
+  import { colorMode, hydrateColorMode } from '../../stores'
   import IconSunny from '~icons/ic/round-wb-sunny'
   import IconMoon from '~icons/octicon/moon-16'
   import IconLaptop from '~icons/bi/laptop'
@@ -11,18 +12,25 @@
     system: [IconLaptop, `dark`, `bi:laptop`],
   } as const
 
+  let hydrated = $state(false)
+
   function set_color_mode() {
     const next = color_mode_icons[$colorMode][1] as typeof $colorMode
     $colorMode = next
   }
 
   const CurrentIcon = $derived(color_mode_icons[$colorMode][0])
+
+  onMount(() => {
+    hydrateColorMode()
+    hydrated = true
+  })
 </script>
 
 <button
   title="Set color mode"
   onclick={set_color_mode}
-  style="display: flex; color: white;"
+  style="display: flex; color: white; opacity: {hydrated ? 1 : 0}; transition: opacity 0.15s;"
 >
   <CurrentIcon title={$colorMode} />
 </button>

src/lib/stores.ts

@@ -8,13 +8,28 @@ export const colorModeKey = `color-mode`
 
 type ColorMode = `light` | `dark` | `system`
 
-export const colorMode = writable<ColorMode>(
-  (has_local_store && localStorage[colorModeKey]) || `system`,
-)
+// Initialize to 'system' for SSR, then hydrate from localStorage on client
+export const colorMode = writable<ColorMode>(`system`)
 
-colorMode.subscribe(
-  (val: ColorMode) => has_local_store && (localStorage[colorModeKey] = val),
-)
+// Flag to track if we've hydrated from localStorage
+let colorModeHydrated = false
+
+export function hydrateColorMode() {
+  if (!colorModeHydrated && has_local_store) {
+    const stored = localStorage[colorModeKey] as ColorMode | undefined
+    if (stored) {
+      colorMode.set(stored)
+    }
+    colorModeHydrated = true
+  }
+}
+
+// Only persist to localStorage AFTER hydration (to avoid overwriting stored value)
+colorMode.subscribe((val: ColorMode) => {
+  if (colorModeHydrated && has_local_store) {
+    localStorage[colorModeKey] = val
+  }
+})
 
 // Custom session store implementation to replace svelte-zoo
 function createSessionStore<T>(key: string, initialValue: T) {

src/routes/+layout.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { afterNavigate } from '$app/navigation'
+  import { browser } from '$app/environment'
   import { Footer, Header } from '$lib'
   import { colorMode, microcopy } from '$lib/stores'
   import type { Snippet } from 'svelte'
@@ -23,6 +24,13 @@
     if (!window.visitedPages) window.visitedPages = [document.referrer]
     window.visitedPages.push(location.pathname + location.search)
   })
+
+  // Sync data-theme attribute when colorMode changes (for client-side theme switching)
+  $effect(() => {
+    if (browser) {
+      document.documentElement.setAttribute('data-theme', $colorMode)
+    }
+  })
 </script>
 
 <!-- Moved these here, from app.html, so these parameter can get different attributes for each site -->
@@ -33,7 +41,6 @@
   <script defer data-domain={$microcopy?.meta?.url} src="/js/script.js"></script>
 
   <meta name="color-scheme" content={$colorMode || `system`} />
-  <link rel="stylesheet" href="/{$colorMode || `system`}-theme.css" />
 </svelte:head>
 
 <Header nav={data.nav} />

static/dark-theme.css

@@ -1,4 +1,5 @@
-:root {
+/* Dark theme - applies when data-theme="dark" or system preference is dark */
+[data-theme='dark'] {
   --text-color: white;
   --link-color: var(--light-blue);
   --hover-color: var(--green);

static/light-theme.css

@@ -1,4 +1,6 @@
-:root {
+/* Light theme - applies when data-theme="light" or system preference is light */
+:root,
+[data-theme='light'] {
   --text-color: black;
   --link-color: var(--blue);
   --hover-color: var(--light-blue);

static/system-theme.css

@@ -1,3 +1,22 @@
-@import url('/light-theme.css') (prefers-color-scheme: light);
+/* System theme - uses media queries to follow OS preference */
+/* Light is the default via light-theme.css :root selector */
 
-@import url('/dark-theme.css') (prefers-color-scheme: dark);
+/* Apply dark theme when system preference is dark AND data-theme is "system" */
+@media (prefers-color-scheme: dark) {
+  [data-theme='system'] {
+    --text-color: white;
+    --link-color: var(--light-blue);
+    --hover-color: var(--green);
+    --body-bg: var(--darker-blue);
+    --accent-bg: var(--alt-gray);
+    --light-bg: var(--dark-gray);
+    --shadow: black;
+    --border-color: var(--dark-green);
+    --heading-color: var(--light-green);
+    --header-bg: var(--darker-blue);
+    --header-color: var(--light-blue);
+    --footer-bg: black;
+    --invert: 1;
+    --transparent: rgba(0, 0, 0, 0.5);
+  }
+}