From 279d79f96e4ef86992d1d3c7f8433a7c909ad096 Mon Sep 17 00:00:00 2001
From: Marco Walz <marco.walz@dfinity.org>
Date: Tue, 28 Apr 2026 14:35:10 +0200
Subject: [PATCH] infra(theme): add mobile theme toggle and default to system
 color scheme

- Add custom Header.astro that renders ThemeSelect on mobile (outside
  the sl-hidden md:sl-flex right-group, which is desktop-only)
- Default theme to prefers-color-scheme instead of hardcoded light in
  both ThemeProvider.astro and ThemeSelect.astro; stored preference
  still takes precedence on return visits
---
 astro.config.mjs                   |  1 +
 src/components/Header.astro        | 91 ++++++++++++++++++++++++++++++
 src/components/ThemeProvider.astro |  5 +-
 src/components/ThemeSelect.astro   | 10 ++--
 4 files changed, 100 insertions(+), 7 deletions(-)
 create mode 100644 src/components/Header.astro

diff --git a/astro.config.mjs b/astro.config.mjs
index 6c348667..7d0a64f8 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -26,6 +26,7 @@ export default defineConfig({
       components: {
         EditLink: "./src/components/EditLink.astro",
         Footer: "./src/components/Footer.astro",
+        Header: "./src/components/Header.astro",
         Hero: "./src/components/Hero.astro",
         SiteTitle: "./src/components/SiteTitle.astro",
         ThemeProvider: "./src/components/ThemeProvider.astro",
diff --git a/src/components/Header.astro b/src/components/Header.astro
new file mode 100644
index 00000000..01733b33
--- /dev/null
+++ b/src/components/Header.astro
@@ -0,0 +1,91 @@
+---
+import config from 'virtual:starlight/user-config';
+
+import LanguageSelect from 'virtual:starlight/components/LanguageSelect';
+import Search from 'virtual:starlight/components/Search';
+import SiteTitle from 'virtual:starlight/components/SiteTitle';
+import SocialIcons from 'virtual:starlight/components/SocialIcons';
+import ThemeSelect from 'virtual:starlight/components/ThemeSelect';
+
+const shouldRenderSearch =
+	config.pagefind || config.components.Search !== '@astrojs/starlight/components/Search.astro';
+---
+
+<div class="header">
+	<div class="title-wrapper sl-flex">
+		<SiteTitle />
+	</div>
+	<div class="sl-flex print:hidden">
+		{shouldRenderSearch && <Search />}
+	</div>
+	{/* Mobile-only theme toggle — desktop uses the one inside right-group */}
+	<div class="md:sl-hidden print:hidden mobile-theme">
+		<ThemeSelect />
+	</div>
+	<div class="sl-hidden md:sl-flex print:hidden right-group">
+		<div class="sl-flex social-icons">
+			<SocialIcons />
+		</div>
+		<ThemeSelect />
+		<LanguageSelect />
+	</div>
+</div>
+
+<style>
+	@layer starlight.core {
+		.header {
+			display: flex;
+			gap: var(--sl-nav-gap);
+			justify-content: space-between;
+			align-items: center;
+			height: 100%;
+		}
+
+		.title-wrapper {
+			overflow: clip;
+			padding: 0.25rem;
+			margin: -0.25rem;
+			min-width: 0;
+		}
+
+		.right-group,
+		.social-icons {
+			gap: 1rem;
+			align-items: center;
+		}
+
+		.social-icons::after {
+			content: '';
+			height: 2rem;
+			border-inline-end: 1px solid var(--sl-color-gray-5);
+		}
+
+		@media (min-width: 50rem) {
+			:global(:root[data-has-sidebar]) {
+				--__sidebar-pad: calc(2 * var(--sl-nav-pad-x));
+			}
+			:global(:root:not([data-has-toc])) {
+				--__toc-width: 0rem;
+			}
+			.header {
+				--__sidebar-width: max(0rem, var(--sl-content-inline-start, 0rem) - var(--sl-nav-pad-x));
+				--__main-column-fr: calc(
+					(
+							100% + var(--__sidebar-pad, 0rem) - var(--__toc-width, var(--sl-sidebar-width)) -
+								(2 * var(--__toc-width, var(--sl-nav-pad-x))) - var(--sl-content-inline-start, 0rem) -
+								var(--sl-content-width)
+						) / 2
+				);
+				display: grid;
+				grid-template-columns:
+					minmax(
+						calc(var(--__sidebar-width) + max(0rem, var(--__main-column-fr) - var(--sl-nav-gap))),
+						auto
+					)
+					1fr
+					auto;
+				align-content: center;
+			}
+		}
+	}
+</style>
diff --git a/src/components/ThemeProvider.astro b/src/components/ThemeProvider.astro
index 867ec14c..7fddc1ae 100644
--- a/src/components/ThemeProvider.astro
+++ b/src/components/ThemeProvider.astro
@@ -1,12 +1,13 @@
 ---
 ---
 
-{/* Inlined to avoid FOUC. Defaults to light; dark is opt-in. Never auto-switches on prefers-color-scheme. */}
+{/* Inlined to avoid FOUC. Defaults to system prefers-color-scheme; overridden by stored user preference. */}
 <script is:inline>
 	window.StarlightThemeProvider = (() => {
 		const storedTheme =
 			typeof localStorage !== 'undefined' && localStorage.getItem('starlight-theme');
-		const theme = storedTheme || 'light';
+		const prefersTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+		const theme = storedTheme || prefersTheme;
 		document.documentElement.dataset.theme = theme === 'dark' ? 'dark' : 'light';
 		return {
 			updatePickers(theme = storedTheme || 'auto') {
diff --git a/src/components/ThemeSelect.astro b/src/components/ThemeSelect.astro
index 1527e380..db1d4516 100644
--- a/src/components/ThemeSelect.astro
+++ b/src/components/ThemeSelect.astro
@@ -23,11 +23,11 @@
 
 	const storageKey = 'starlight-theme';
 
-	const parseTheme = (theme: unknown): Theme =>
-		theme === 'dark' ? 'dark' : 'light';
-
-	const loadTheme = (): Theme =>
-		parseTheme(typeof localStorage !== 'undefined' && localStorage.getItem(storageKey));
+	const loadTheme = (): Theme => {
+		const stored = typeof localStorage !== 'undefined' ? localStorage.getItem(storageKey) : null;
+		if (stored === 'dark' || stored === 'light') return stored;
+		return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+	};
 
 	function storeTheme(theme: Theme): void {
 		if (typeof localStorage !== 'undefined') {