🤖 fix: apply theme synchronously to document before React renders

The key insight: React's useLayoutEffect runs AFTER initial render, but
Chromatic needs the theme applied BEFORE rendering starts to avoid
flashing and capture correct snapshots.

Solution: Apply theme to document.documentElement synchronously in the
decorator, before returning the ThemeProvider. This ensures:
- Light mode stories render in light theme immediately
- Dark mode stories render in dark theme immediately
- No flash of wrong theme during Chromatic snapshots

Credit: simpler synchronous approach beats async React lifecycle.

Author: ethanndickson

.storybook/preview.tsx

@@ -20,14 +20,15 @@ const preview: Preview = {
   },
   decorators: [
     (Story, context) => {
-      // Chromatic modes don't set context.globals during local development
-      // They only work during Chromatic's CI snapshot process
-      // For local development, globals.theme can be set via the toolbar
       const mode = context.globals.theme as ThemeMode | undefined;
 
-      // When no explicit mode is set (locally or via toolbar), don't force a theme
-      // Let ThemeProvider use its default behavior (system preference / localStorage)
-      // When Chromatic runs with modes, it will set globals.theme appropriately
+      // Apply theme synchronously to document BEFORE React renders
+      // This ensures Chromatic snapshots capture the correct theme without flashing
+      if (mode && typeof document !== "undefined") {
+        document.documentElement.dataset.theme = mode;
+        document.documentElement.style.colorScheme = mode;
+      }
+      
       return (
         <ThemeProvider forcedTheme={mode}>
           <Story />