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

TusharThakur04 · TusharThakur04 · commit 501c20b68065 · 2026-04-18T19:57:01.000+05:30
diff --git a/src/generators/web/template.html b/src/generators/web/template.html
@@ -19,7 +19,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,25 @@
+'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).
+ */
+
+export default `(function initializeTheme() {
+  const THEME_STORAGE_KEY = 'theme';
+  const THEME_DATA_ATTRIBUTE = 'data-theme';
+  const DARK_QUERY = '(prefers-color-scheme: dark)';
+
+  const savedUserPreference = localStorage.getItem(THEME_STORAGE_KEY);
+  const systemSupportsDarkMode = window.matchMedia(DARK_QUERY).matches;
+
+  const shouldApplyDark =
+    savedUserPreference === 'dark' ||
+    (savedUserPreference === 'system' && systemSupportsDarkMode) ||
+    (!savedUserPreference && systemSupportsDarkMode);
+
+  const themeToApply = shouldApplyDark ? 'dark' : 'light';
+
+  document.documentElement.setAttribute(THEME_DATA_ATTRIBUTE, themeToApply);
+  document.documentElement.style.colorScheme = themeToApply;
+})();`.trim();
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 themeScript from '../ui/theme-script.mjs';
 
 /**
  * Populates a template string by evaluating it as a JavaScript template literal,
@@ -137,6 +138,7 @@ export async function processJSXEntries(entries, template) {
         importMap: clientBundle.importMap?.replaceAll('/', root) ?? '',
         entrypoint: `${data.api}.js?${randomUUID()}`,
         speculationRules: SPECULATION_RULES,
+        themeScript,
         root,
         metadata: data,
         config,
