Dark Mode Design System Tokens

Dark mode fails when teams invert hex values without rethinking elevation and semantic roles. Tokens express intent—surface-raised, text-primary—not literal colors.

Semantic color roles

• bg.canvas, bg.subtle, bg.elevated
• text.primary, text.muted, text.inverse
• border.default, border.focus
• status.success, status.warning, status.error

Map each role in light and dark with verified contrast pairs.

Elevation without gray mush

Dark UI uses lighter surfaces for higher elevation—not shadows alone:

Contrast rules

Body text still needs 4.5:1 against its surface. Muted text is the common failure—test #94a3b8 on #0f172a explicitly.

Implementation

:root { --text-primary: #0f172a; }
[data-theme="dark"] { --text-primary: #f1f5f9; }

Prefer data-theme over prefers-color-scheme alone—user toggle must win.

Dark mode is a first-class theme—design it alongside light, not as an afterthought filter.