Dark Mode Implementation Template

Build light mode first, but build it on semantic tokens from day one. If your color system uses tokens, adding dark mode is a token value swap. If your color system uses hardcoded hex values, adding dark mode requires a full audit and migration before you can even start. The [design system documentation template](/templates/design-system-documentation-template) covers how to set up token architecture from the beginning.

User-uploaded images, rich text, and embedded content cannot be automatically themed. The best practice is to display user content in its original form inside a container that has a consistent background (either neutral or slightly elevated from the page background). Do not apply CSS filters (brightness, invert) to user content. It distorts colors and creates a poor reading experience.

Emails and PDFs should always render in light mode unless you can detect the recipient's preference (you usually cannot). Dark mode is a display-time preference. Generated documents and transactional emails should use a neutral light theme for maximum compatibility.

Track adoption: what percentage of users enable dark mode within 30 days of launch? Track retention: do dark mode users have higher session duration or lower bounce rates during evening hours? Track support: do dark mode users report fewer eye strain or accessibility complaints? Baseline these metrics before launch. ---