fix: resolve flash of unstyled content in dark mode by TusharThakur04 · Pull Request #766 · nodejs/doc-kit

TusharThakur04 · 2026-04-13T14:23:51Z

Description

This PR resolves the FOUC by resolving system to dark or light using matchMedia.
Earlier system was directly being applied as set-theme = system

Validation

before :

Screencast.from.2026-04-13.19-26-34.webm

after :

Screencast.from.2026-04-13.19-24-03.webm

Related Issues

n/a

Check List

I have read the Contributing Guidelines and made commit messages that follow the guideline.
I have run node --run test and all tests passed.
I have check code formatting with node --run format & node --run lint.
I've covered new added functionality with unit tests if necessary.

cursor · 2026-04-13T14:23:59Z

PR Summary

Low Risk
Low risk, localized change to the static HTML template/theme bootstrap logic; main risk is incorrect theme selection or unexpected behavior in browsers with restricted localStorage/matchMedia.

Overview
Fixes dark-mode Flash of Unstyled Content by replacing the one-liner theme bootstrap in template.html with an inlined, shared themeScript that resolves saved preference (including system) to an actual dark/light theme before first paint.

The web generator now imports and injects this themeScript during HTML rendering (processing.mjs), centralizing early theme application and ensuring data-theme and colorScheme are set consistently.

^{Reviewed by Cursor Bugbot for commit 501c20b. Bugbot is set up for automated code reviews on this repo. Configure here.}

vercel · 2026-04-13T14:24:12Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Apr 18, 2026 2:28pm

canerakdas · 2026-04-15T09:25:35Z


  <!-- 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>(function(){var p=localStorage.getItem("theme");var t=(!p||p==="system")?(matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light"):p;document.documentElement.setAttribute("data-theme",t);document.documentElement.style.colorScheme=t;})();</script>


I think we should make this code block more readable for developers who want to contribute or review it. Instead of writing it as a single line, using more descriptive variable names shouldn't significantly impact the file size. @nodejs/web-infra WDYT?

If that's the case this script source should be in its own file and then inlined via a template string {{}}

avivkeller · 2026-04-15T20:09:47Z

This seems highly complex

TusharThakur04 · 2026-04-15T20:27:06Z

the {$themeScript} literal is being replaced by newly created themeScript by generate.mjs

it is done so that the script is available before rendering the html and there is no latency which could have happened if browser makes request for the themeScript.mjs if we use src inside the script tag

ovflowd · 2026-04-16T10:27:56Z

+
+  // Wrap theme script in script tag and replace the placeholder
+  const inlinedThemeScript = `<script>${themeScriptContent}</script>`;
+  template = template.replace('${themeScript}', inlinedThemeScript);


Don't use .replace(), I believe that @avivkeller implemented a system to automatically evaluate such template variables?

ovflowd · 2026-04-16T10:28:13Z

+  It injects an inline script that initializes the theme (light/dark)
+  before the page renders to avoid Flash of Unstyled Content (FOUC).
+-->
+  ${themeScript}


Suggested change

${themeScript}

<script type="javascript">${themeScript}</script>

ovflowd · 2026-04-16T10:28:21Z


-  <!-- 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>
+<!--


No need for this comment.

ovflowd · 2026-04-16T10:28:53Z

+
+  // Read the theme script from UI folder
+  const themeScriptPath = join(import.meta.dirname, 'ui', 'theme-script.mjs');
+  const themeScriptContent = await readFile(themeScriptPath, 'utf-8');


We shouldn't ue fs the idea is to use our rolldown pipeline for this script, so it gets properly minified and transformed.

Otherwise the file doesn't get minified, which is the idea behind separating src<>final result.

codecov · 2026-04-18T13:30:06Z

Codecov Report

❌ Patch coverage is 50.00000% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 77.95%. Comparing base (3d00fa8) to head (501c20b).
⚠️ Report is 7 commits behind head on main.

Files with missing lines	Patch %	Lines
src/generators/web/utils/processing.mjs	50.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #766      +/-   ##
==========================================
- Coverage   78.43%   77.95%   -0.49%     
==========================================
  Files         157      159       +2     
  Lines       13962    14057      +95     
  Branches     1152     1152              
==========================================
+ Hits        10951    10958       +7     
- Misses       3006     3094      +88     
  Partials        5        5

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3c1f1be. Configure here.}

TusharThakur04 requested a review from a team as a code owner April 13, 2026 14:23

vercel bot deployed to Preview April 13, 2026 14:25 View deployment

cursor bot reviewed Apr 13, 2026

View reviewed changes

Comment thread src/generators/web/template.html Outdated

TusharThakur04 force-pushed the fix/dark-mode-FOUC branch from 893ddea to 4ae89b4 Compare April 13, 2026 14:29

vercel bot deployed to Preview April 13, 2026 14:30 View deployment

canerakdas reviewed Apr 15, 2026

View reviewed changes

TusharThakur04 force-pushed the fix/dark-mode-FOUC branch from 4ae89b4 to 34de276 Compare April 15, 2026 18:12

vercel bot deployed to Preview April 15, 2026 18:12 View deployment

TusharThakur04 requested review from canerakdas and ovflowd April 15, 2026 18:18

ovflowd reviewed Apr 16, 2026

View reviewed changes

TusharThakur04 force-pushed the fix/dark-mode-FOUC branch from 34de276 to 0b53971 Compare April 18, 2026 13:29

TusharThakur04 requested a review from ovflowd April 18, 2026 13:29

vercel bot deployed to Preview April 18, 2026 13:30 View deployment

cursor bot reviewed Apr 18, 2026

View reviewed changes

Comment thread src/generators/web/utils/processing.mjs Outdated

TusharThakur04 force-pushed the fix/dark-mode-FOUC branch from 0b53971 to 3c1f1be Compare April 18, 2026 13:43

vercel bot deployed to Preview April 18, 2026 13:43 View deployment

cursor bot reviewed Apr 18, 2026

View reviewed changes

Comment thread src/generators/web/ui/theme-script.mjs Outdated

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

501c20b

TusharThakur04 force-pushed the fix/dark-mode-FOUC branch from 3c1f1be to 501c20b Compare April 18, 2026 14:27

vercel bot deployed to Preview April 18, 2026 14:28 View deployment

	${themeScript}
	<script type="javascript">${themeScript}</script>

Conversation

TusharThakur04 commented Apr 13, 2026

Description

Validation

before :

after :

Related Issues

Check List

Uh oh!

cursor bot commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

vercel bot commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

canerakdas Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

ovflowd Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

avivkeller commented Apr 15, 2026

Uh oh!

TusharThakur04 commented Apr 15, 2026

Uh oh!

ovflowd Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

ovflowd Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

ovflowd Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

ovflowd Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

ovflowd Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Apr 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

cursor bot commented Apr 13, 2026 •

edited

Loading

vercel bot commented Apr 13, 2026 •

edited

Loading

codecov bot commented Apr 18, 2026 •

edited

Loading