fix: resolve flash of unstyled content in dark mode (#766)

TusharThakur04 · web-flow · commit b96e4e56ae19 · 2026-06-16T10:44:42.000-05:00
diff --git a/src/generators/web/template.html b/src/generators/web/template.html
@@ -17,7 +17,7 @@
     href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono&family=Open+Sans:ital,wght@0,300..800;1,300..800" />
 
   <!-- Apply theme before paint to avoid Flash of Unstyled Content -->
-  <script>document.documentElement.setAttribute("data-theme", document.documentElement.style.colorScheme = localStorage.getItem("theme") || (matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"));</script>
+  <script>${themeScript}</script>
   <script type="importmap">${importMap}</script>
   <script type="speculationrules">${speculationRules}</script>
 </head>
diff --git a/src/generators/web/ui/theme-script.mjs b/src/generators/web/ui/theme-script.mjs
@@ -0,0 +1,26 @@
+'use strict';
+
+/**
+ * This script is designed to be inlined in the <head> of the HTML template.
+ * It must execute BEFORE the body renders to prevent a Flash of Unstyled Content (FOUC).
+ */
+function initializeTheme() {
+  var THEME_STORAGE_KEY = 'theme';
+  var THEME_DATA_ATTRIBUTE = 'data-theme';
+  var DARK_QUERY = '(prefers-color-scheme: dark)';
+
+  var savedUserPreference = localStorage.getItem(THEME_STORAGE_KEY);
+  var systemSupportsDarkMode = window.matchMedia(DARK_QUERY).matches;
+
+  var shouldApplyDark =
+    savedUserPreference === 'dark' ||
+    (savedUserPreference === 'system' && systemSupportsDarkMode) ||
+    (!savedUserPreference && systemSupportsDarkMode);
+
+  var themeToApply = shouldApplyDark ? 'dark' : 'light';
+
+  document.documentElement.setAttribute(THEME_DATA_ATTRIBUTE, themeToApply);
+  document.documentElement.style.colorScheme = themeToApply;
+}
+
+export var THEME_SCRIPT = `(${initializeTheme.toString()})();`;
diff --git a/src/generators/web/utils/processing.mjs b/src/generators/web/utils/processing.mjs
@@ -13,6 +13,7 @@ import getConfig from '../../../utils/configuration/index.mjs';
 import { populate } from '../../../utils/configuration/templates.mjs';
 import { minifyHTML } from '../../../utils/html-minifier.mjs';
 import { SPECULATION_RULES } from '../constants.mjs';
+import { THEME_SCRIPT } from '../ui/theme-script.mjs';
 
 /**
  * Populates a template string by evaluating it as a JavaScript template literal,
@@ -195,6 +196,7 @@ export async function processJSXEntries(
         importMap: clientBundle.importMap?.replaceAll('/', root) ?? '',
         entrypoint: `${data.api}.js?${randomUUID()}`,
         speculationRules: SPECULATION_RULES,
+        themeScript: THEME_SCRIPT,
         root,
         metadata: data,
         config,
