Problem
On some browsers (especially Chrome with light OS theme), there is a brief flash of unstyled/light content before the dark theme script in <head> fires. This is a FOUC (Flash of Unstyled Content).
Root cause
The inline theme script in <head> runs before CSS is parsed. If the CSS file is large or the browser delays parsing, the page renders without a theme briefly.
Steps to reproduce
- Set OS to light mode
- Hard-refresh any topic page
- Observe ~100ms flash of light background before dark theme applies
Fix direction
Two options:
- CSS custom property default: Set the dark theme variables as the default in
:root (no [data-theme] selector needed for dark). Only override for [data-theme="light"]. This way even before JS runs, dark theme is applied via CSS.
- Critical CSS inline: Inline the minimum theme variables (
--bg, --surface, --text) directly in <head> as a <style> block so theme colors apply before external CSS loads.
Option 1 is cleaner. It only requires restructuring css/style.css theme variable declarations.
Files
css/style.css — restructure :root vs [data-theme] variable assignments
Difficulty: Beginner — CSS custom properties only
Problem
On some browsers (especially Chrome with light OS theme), there is a brief flash of unstyled/light content before the dark theme script in
<head>fires. This is a FOUC (Flash of Unstyled Content).Root cause
The inline theme script in
<head>runs before CSS is parsed. If the CSS file is large or the browser delays parsing, the page renders without a theme briefly.Steps to reproduce
Fix direction
Two options:
:root(no[data-theme]selector needed for dark). Only override for[data-theme="light"]. This way even before JS runs, dark theme is applied via CSS.--bg,--surface,--text) directly in<head>as a<style>block so theme colors apply before external CSS loads.Option 1 is cleaner. It only requires restructuring
css/style.csstheme variable declarations.Files
css/style.css— restructure:rootvs[data-theme]variable assignmentsDifficulty: Beginner — CSS custom properties only