fix: storybook initial theme for vanilla provider

Author: gndz07

.storybook/preview.jsx

@@ -7,6 +7,8 @@ import { themes } from 'storybook/theming';
 import { globalCss } from '../';
 import { FaencyProvider } from '../components/FaencyProvider';
 import { darkTheme, lightTheme } from '../stitches.config';
+import { VanillaExtractThemeProvider } from '../styles/themeContext';
+import { themes as vanillaThemes } from '../styles/themes.css';
 
 const channel = addons.getChannel();
 
@@ -17,21 +19,42 @@ const channel = addons.getChannel();
 const getInitialThemePreference = () => {
   if (typeof window === 'undefined') return false;
 
-  // Check stored preference first
+  // Check stored preference
   const stored = localStorage.getItem('sb-addon-themes-3');
   if (stored) {
     try {
       const parsed = JSON.parse(stored);
-      if (parsed.current === 'dark') return true;
-    } catch (e) {
-      // Fall through to system preference
+      if (parsed.current) {
+        return parsed.current === 'dark';
+      }
+    } catch (error) {
+      console.warn('Failed to parse Storybook theme preference:', error);
     }
   }
 
-  // Fallback to system preference
+  // Fallback to system preference only if no stored value or parse error
   return window.matchMedia('(prefers-color-scheme: dark)').matches;
 };
 
+// Initialize vanilla-extract theme class immediately on script load
+if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+  const initialTheme = getInitialThemePreference() ? 'dark' : 'light';
+  const themeClass = vanillaThemes[initialTheme]['blue'];
+
+  function applyInitialTheme() {
+    Object.values(vanillaThemes.light).forEach((cls) => document.body.classList.remove(cls));
+    Object.values(vanillaThemes.dark).forEach((cls) => document.body.classList.remove(cls));
+
+    document.body.classList.add(themeClass);
+  }
+
+  if (document.body) {
+    applyInitialTheme();
+  } else {
+    document.addEventListener('DOMContentLoaded', applyInitialTheme);
+  }
+}
+
 export const parameters = {
   controls: {
     matchers: {
@@ -72,38 +95,14 @@ const globalStyle = globalCss({
 });
 
 const VanillaProviderWrapper = ({ children, isDark, primaryColor }) => {
-  const [Provider, setProvider] = React.useState(null);
-  const [loading, setLoading] = React.useState(true);
-
-  React.useEffect(() => {
-    import('../styles/themeContext')
-      .then((module) => {
-        setProvider(() => module.VanillaExtractThemeProvider);
-        setLoading(false);
-      })
-      .catch((err) => {
-        console.warn('VanillaExtractThemeProvider failed to load:', err);
-        setLoading(false);
-      });
-  }, []);
-
-  if (loading) {
-    return React.createElement('div', { style: { padding: '24px' } }, 'Loading theme system...');
-  }
-
-  if (Provider) {
-    return React.createElement(
-      Provider,
-      {
-        forcedTheme: isDark ? 'dark' : 'light',
-        primaryColor,
-      },
-      children,
-    );
-  }
-
-  // If provider failed to load, just return children (Stitches fallback)
-  return children;
+  return React.createElement(
+    VanillaExtractThemeProvider,
+    {
+      forcedTheme: isDark ? 'dark' : 'light',
+      primaryColor,
+    },
+    children,
+  );
 };
 
 export const decorators = [
@@ -120,6 +119,17 @@ export const decorators = [
       return () => channel.removeListener(DARK_MODE_EVENT_NAME, setDark);
     }, []);
 
+    // Apply vanilla-extract theme class before first render to prevent flash
+    React.useLayoutEffect(() => {
+      const resolvedTheme = isDark ? 'dark' : 'light';
+      const themeClass = vanillaThemes[resolvedTheme]['blue'];
+
+      Object.values(vanillaThemes.light).forEach((cls) => document.body.classList.remove(cls));
+      Object.values(vanillaThemes.dark).forEach((cls) => document.body.classList.remove(cls));
+
+      document.body.classList.add(themeClass);
+    }, [isDark]);
+
     return (
       <VanillaProviderWrapper isDark={isDark} primaryColor="blue">
         <FaencyProvider>

stories/ThemeTest.stories.tsx

@@ -223,6 +223,3 @@ export const ThemeAPITest: StoryFn = () => {
 
   return <ThemeInfo />;
 };
-
-PrimaryColorShowcase.storyName = 'Primary Color Showcase';
-ThemeAPITest.storyName = 'Theme API Test';

styles/themeContext.tsx

@@ -1,4 +1,4 @@
-import React, { createContext, useContext, useEffect, useState } from 'react';
+import React, { createContext, useContext, useEffect, useLayoutEffect, useState } from 'react';
 
 import { darkColors, lightColors } from '../colors';
 import { PrimaryColor, themes } from './themes.css';
@@ -33,7 +33,9 @@ export function VanillaExtractThemeProvider({
   const [mode, setMode] = useState<ThemeMode>(defaultTheme);
   const [appliedPrimaryColor, setPrimaryColor] = useState<PrimaryColor>(primaryColor);
   const [systemTheme, setSystemTheme] = useState<'light' | 'dark'>(() => {
-    // Initialize with actual system preference to avoid flash
+    if (forcedTheme) {
+      return forcedTheme;
+    }
     if (typeof window !== 'undefined') {
       return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
     }
@@ -45,6 +47,11 @@ export function VanillaExtractThemeProvider({
   }, [primaryColor]);
 
   useEffect(() => {
+    if (forcedTheme) {
+      setSystemTheme(forcedTheme);
+      return;
+    }
+
     const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
     setSystemTheme(mediaQuery.matches ? 'dark' : 'light');
 
@@ -54,13 +61,12 @@ export function VanillaExtractThemeProvider({
 
     mediaQuery.addEventListener('change', handler);
     return () => mediaQuery.removeEventListener('change', handler);
-  }, []);
+  }, [forcedTheme]);
 
   const resolvedTheme: 'light' | 'dark' = forcedTheme || (mode === 'system' ? systemTheme : mode);
 
   const baseColors = resolvedTheme === 'dark' ? darkColors : lightColors;
 
-  // Add semantic colors based on the current theme and primary color
   const semanticColors =
     resolvedTheme === 'dark'
       ? {
@@ -115,14 +121,13 @@ export function VanillaExtractThemeProvider({
     ...semanticColors,
   };
 
-  useEffect(() => {
+  // Use useLayoutEffect to apply theme class synchronously before paint
+  useLayoutEffect(() => {
     const themeClass = themes[resolvedTheme][appliedPrimaryColor];
 
-    // Remove all theme classes
     Object.values(themes.light).forEach((cls) => document.body.classList.remove(cls));
     Object.values(themes.dark).forEach((cls) => document.body.classList.remove(cls));
 
-    // Add current theme class
     document.body.classList.add(themeClass);
 
     return () => {