From f67cffc11cc1d31fa0af795afb65111cd29d5a89 Mon Sep 17 00:00:00 2001
From: Renie Joshi <reniejoshi@users.noreply.github.com>
Date: Sat, 1 Aug 2026 12:03:42 -0700
Subject: [PATCH 1/3] Fix light/dark mode based on browser default

---
 src/starlightOverrides/Header.astro | 39 ++++++++++++++++++++++-------
 1 file changed, 30 insertions(+), 9 deletions(-)

diff --git a/src/starlightOverrides/Header.astro b/src/starlightOverrides/Header.astro
index 1ceca959..2f4d055b 100644
--- a/src/starlightOverrides/Header.astro
+++ b/src/starlightOverrides/Header.astro
@@ -373,12 +373,17 @@ for (const section of sidebarSections) {
             }
         };
 
-        const applyTheme = (/** @type {'light' | string} */ theme) => {
+        const applyTheme = (
+            /** @type {'light' | string} */ theme,
+            store = false,
+        ) => {
             const html = document.documentElement;
             const normalized = theme === 'light' ? 'light' : 'dark';
 
             html.dataset.theme = normalized;
-            setStoredTheme(normalized);
+            // Only persist an explicit user choice. Browser-derived themes must
+            // stay un-stored so the site keeps following the OS/browser setting.
+            if (store) setStoredTheme(normalized);
             // @ts-expect-error javascript...
             if (window.StarlightThemeProvider?.updatePickers) {
                 // @ts-expect-error javascript...
@@ -428,22 +433,38 @@ for (const section of sidebarSections) {
             });
         };
 
+        const getPreferredTheme = () =>
+            window.matchMedia('(prefers-color-scheme: light)').matches
+                ? 'light'
+                : 'dark';
+
         const init = () => {
-            let theme = getStoredTheme();
+            const stored = getStoredTheme();
+            const explicit =
+                stored === 'light' || stored === 'dark' ? stored : null;
 
-            if (!theme) {
-                theme = 'dark';
-            }
-            applyTheme(theme);
+            applyTheme(explicit || getPreferredTheme());
 
             document.querySelectorAll('[data-theme-toggle]').forEach((btn) => {
                 btn.addEventListener('click', () => {
-                    const current = getStoredTheme() || 'dark';
+                    const current =
+                        document.documentElement.dataset.theme ||
+                        getPreferredTheme();
                     const next = current === 'dark' ? 'light' : 'dark';
-                    applyTheme(next);
+                    applyTheme(next, true);
                 });
             });
 
+            const schemeQuery = window.matchMedia(
+                '(prefers-color-scheme: light)',
+            );
+            const onSchemeChange = () => {
+                if (!getStoredTheme()) {
+                    applyTheme(getPreferredTheme());
+                }
+            };
+            schemeQuery.addEventListener('change', onSchemeChange);
+
             initMobileMenu();
         };
 

From 803f58cda1fdb8733bf932c2cf6643e46f3d1bf7 Mon Sep 17 00:00:00 2001
From: Renie Joshi <reniejoshi@users.noreply.github.com>
Date: Fri, 4 Sep 2026 15:48:01 -0700
Subject: [PATCH 2/3] Apply copilot suggestion

---
 src/starlightOverrides/Header.astro | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/src/starlightOverrides/Header.astro b/src/starlightOverrides/Header.astro
index 9927d1aa..7b277492 100644
--- a/src/starlightOverrides/Header.astro
+++ b/src/starlightOverrides/Header.astro
@@ -245,10 +245,9 @@ const { hasSidebar } = Astro.locals.starlightRoute;
             }
         };
 
+        const colorScheme = window.matchMedia('(prefers-color-scheme: light)');
         const getPreferredTheme = () =>
-            window.matchMedia('(prefers-color-scheme: light)').matches
-                ? 'light'
-                : 'dark';
+            colorScheme.matches ? 'light' : 'dark';
 
         const init = () => {
             const stored = getStoredTheme();
@@ -257,6 +256,18 @@ const { hasSidebar } = Astro.locals.starlightRoute;
 
             applyTheme(explicit || getPreferredTheme());
 
+            // Follow OS/browser changes unless the user has explicitly chosen a theme.
+            const onSchemeChange = () => {
+                if (getStoredTheme() == null) applyTheme(getPreferredTheme());
+            };
+            if (!explicit) {
+                if (typeof colorScheme.addEventListener === 'function') {
+                    colorScheme.addEventListener('change', onSchemeChange);
+                } else if (typeof colorScheme.addListener === 'function') {
+                    colorScheme.addListener(onSchemeChange);
+                }
+            }
+
             document.querySelectorAll('[data-theme-toggle]').forEach((btn) => {
                 btn.addEventListener('click', () => {
                     const current =

From a9525e505ca938871d906ee13bfa53878c07bb99 Mon Sep 17 00:00:00 2001
From: Renie Joshi <177680549+reniejoshi@users.noreply.github.com>
Date: Fri, 4 Sep 2026 15:57:08 -0700
Subject: [PATCH 3/3] Improve theme application logic on scheme change

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 src/starlightOverrides/Header.astro | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/starlightOverrides/Header.astro b/src/starlightOverrides/Header.astro
index 7b277492..b66cc821 100644
--- a/src/starlightOverrides/Header.astro
+++ b/src/starlightOverrides/Header.astro
@@ -258,7 +258,10 @@ const { hasSidebar } = Astro.locals.starlightRoute;
 
             // Follow OS/browser changes unless the user has explicitly chosen a theme.
             const onSchemeChange = () => {
-                if (getStoredTheme() == null) applyTheme(getPreferredTheme());
+                const stored = getStoredTheme();
+                if (stored !== 'light' && stored !== 'dark') {
+                    applyTheme(getPreferredTheme());
+                }
             };
             if (!explicit) {
                 if (typeof colorScheme.addEventListener === 'function') {