Dark mode is not a color swap. Every time I see a team "add dark mode" by inverting their palette, I know they will spend the next three months fixing the things that broke. Here are the three that always break.
1. SHADOWS BECOME INVISIBLE
On a white background, a box-shadow creates depth. On a black background, the same shadow disappears — dark on dark. The elevation hierarchy you built with shadows is gone. You need to replace shadows with borders: 1px solid var(--zt-line) on every surface that previously relied on a shadow for separation.
"In dark mode, the border is the shadow. Plan for it from the start."
2. PURE WHITE TEXT BURNS
color: #fff on a dark background is too bright. The screen emits light directly into the reader's eyes, and pure white is the maximum emission. Drop to #f3f3ef or #e8e8e4 — a 3-5% reduction in luminance makes a surprising difference in comfort over long reading sessions.
The Muted Text Token
Define --zt-text: #f3f3ef as your default text color, not #fff. Reserve pure white for display headlines where the impact is intentional. Body text should never be pure white in a dark theme.
3. ACCENT COLORS OVERSATURATE
An accent color that looks vibrant on white can look radioactive on black. The contrast against a dark surface is higher, so the color reads as louder. You usually need to desaturate the accent by 10-15% or darken it slightly when moving to dark mode. Test it in context — never trust the color picker.
CONCLUSION
Dark mode is a redesign, not a toggle. Borders replace shadows, text dims slightly, and accents calm down. If you plan for these three from the start, the flip is a theme change. If you don't, it's a six-month bug hunt.