From e225a988faac193f38b20de68949797a09423058 Mon Sep 17 00:00:00 2001
From: jonathanayubausara-a11y <jonathanayubausara@gmail.com>
Date: Sat, 27 Jun 2026 13:14:44 +0000
Subject: [PATCH] fix(theme): eliminate dark mode FOUC with inline bootstrap
 script (#460)

Inject a synchronous blocking <script> in <head> that reads the
persisted theme from localStorage (matching next-themes storageKey="theme")
and applies the `dark` class on <html> before the first paint. Prevents
the flash of light content for dark-mode users on hard reload, and
keeps CLS at 0 (classList mutations are non-geometric).
suppressHydrationWarning on <html> absorbs the className diff that
next-themes writes again after hydration.
---
 src/app/layout.tsx | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index e4ffa4e8..1791bbd3 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -5,6 +5,20 @@ import "@/utils/earlyErrorSuppression";
 import { ClientProviders } from "@/components/ClientProviders";
 import { headers } from "next/headers";
 
+/**
+ * Synchronous blocking script that runs before React hydrates.
+ * It reads the persisted theme from localStorage (matching the
+ * `storageKey="theme"` configured on next-themes) and applies (or
+ * removes) the `dark` class on the <html> element so the first paint
+ * already matches the user's preferred theme. Without this script,
+ * dark-mode users see a flash of light content (FOUC) on hard reload
+ * because next-themes' class attribute is only applied after hydration.
+ *
+ * CLS = 0 because the classList mutation is non-geometric and React
+ * reconciles the className diff silently thanks to `suppressHydrationWarning`.
+ */
+const themeBootstrapScript = `(function(){try{var t=localStorage.getItem('theme');var d=t==='dark'||((t===null||t==='system')&&window.matchMedia&&window.matchMedia('(prefers-color-scheme: dark)').matches);var c=document.documentElement.classList;c.remove('light','dark');if(d){c.add('dark');}else if(t==='light'){c.add('light');}document.documentElement.style.colorScheme=d?'dark':'light';}catch(e){}})();`;
+
 const geistSans = Geist({
   variable: "--font-geist-sans",
   subsets: ["latin"],
@@ -39,6 +53,18 @@ export default async function RootLayout({
       dir={isRTL ? "rtl" : "ltr"}
       suppressHydrationWarning
     >
+      <head>
+        {/*
+          dangerouslySetInnerHTML is used because this script must run
+          synchronously before paint. It is a static string we control,
+          so there is no XSS risk. `suppressHydrationWarning` on <html>
+          absorbs the className diff that next-themes writes after hydration.
+        */}
+        <script
+          // eslint-disable-next-line react/no-danger
+          dangerouslySetInnerHTML={{ __html: themeBootstrapScript }}
+        />
+      </head>
       <body
         className={`${geistSans.variable} ${geistMono.variable} bg-background font-sans text-foreground antialiased`}
       >
