Dark Mode Implementation

Dark mode provides an alternative color scheme with dark backgrounds and light text, requiring careful color and contrast management.

stellae.design

Design Principles

Dark mode inverts the typical light-background UI to use dark backgrounds with light foreground text and elements. Benefits: reduced eye strain in low-light conditions, battery savings on OLED screens, and user preference/accessibility. Implementation is more than inverting colors — it requires a complete dark color palette with appropriate contrast ratios, careful handling of images/shadows/elevation, and respecting the prefers-color-scheme system preference.

Why It Matters

Dark mode implementation is far more than inverting a color palette — it is a systematic design and engineering challenge that requires rethinking color semantics, contrast relationships, image treatment, elevation hierarchy, and user preference persistence across an entire product surface. Done well, dark mode reduces eye strain in low-light environments, saves battery on OLED screens, and provides users with meaningful personalization. Done poorly, it introduces accessibility failures through insufficient contrast, creates visual inconsistencies where some elements invert correctly and others do not, and increases maintenance burden when design tokens are not properly abstracted.

Real-World Examples

GitHub's dark mode implementation

GitHub offers multiple dark mode variants — dark default, dark dimmed, and dark high contrast — each designed for different environments and preferences, all built on a semantic token system called Primer Primitives. The token architecture means that every component in the system automatically adapts to the selected theme without component-level overrides, and new components inherit correct dark mode behavior by default. The multiple variants demonstrate that dark mode is not a single design but a spectrum of preferences that users should be able to choose between.

Slack's dark mode color system

Slack's dark mode reduces color saturation across its entire palette, uses surface-level lightness to communicate elevation, and adjusts the visual treatment of user-generated content like emoji and shared images to ensure they remain legible. The implementation handles edge cases that many dark modes miss — syntax highlighting in code blocks, colored status indicators, and custom sidebar themes all adapt to the dark surface without manual intervention. Slack's approach shows that robust dark mode requires auditing every visual element, not just the primary background and text colors.

Counter-example

Naive CSS filter inversion

A web application implements dark mode by applying `filter: invert(1)` to the entire page, which mathematically inverts all colors including images, videos, branded elements, and already-dark UI components like code blocks. The result is photographs rendered as negatives, brand logos in wrong colors, and some elements being double-inverted back to their light mode appearance in an inconsistent patchwork. This shortcut produces a technically functional but visually broken dark mode that undermines user trust and creates more problems than it solves.

Role-Specific Guidance

Common Mistakes

• The most common mistake is treating dark mode as an afterthought that can be added on top of a finished light design, rather than designing both modes simultaneously from the start — retrofitting dark mode onto a product that was designed without semantic color tokens requires touching every component individually. Another frequent error is using pure black (#000000) as the primary background, which creates maximum contrast that causes eye strain during extended reading sessions and makes OLED screens' pixel-off boundaries visible as smearing artifacts during scrolling. Teams also forget to test dark mode with sufficient rigor — checking the main screens while missing states like error messages, tooltips, empty states, loading skeletons, and third-party embedded content that may not respect the theme.