Implementing Dark Modes With CSS

Why Dark Mode Matters

Dark mode has evolved from a developer preference to an essential user experience feature. Modern websites must support theme switching that respects user preferences, persists choices, and delivers consistent performance.

According to Hoverify's dark mode implementation guide, users increasingly expect the ability to customize their viewing experience based on device settings and personal preference. This guide covers implementing dark mode using pure CSS with minimal JavaScript, leveraging the latest CSS features for maintainable, performant theme switching.

User Experience Benefits

Dark mode implementation directly impacts user satisfaction and engagement. Studies consistently show that users prefer having control over their viewing experience, particularly for applications they use extensively throughout the day. The ability to switch between light and dark themes accommodates different environments, times of day, and individual visual preferences. For websites focused on CSS content, implementing proper theming demonstrates attention to detail that clients and users appreciate.

From a practical standpoint, dark mode can significantly reduce battery consumption on devices with OLED or AMOLED displays, where individual pixels can be completely turned off for black backgrounds. This benefit is particularly relevant for mobile users who spend significant time browsing on their devices, as documented in Hoverify's accessibility research.

Accessibility Considerations

Beyond personal preference, dark mode serves important accessibility purposes. Users with certain visual conditions may find light text on dark backgrounds easier to read, reducing eye strain and improving overall readability. Implementing proper contrast ratios ensures that text remains legible regardless of the selected theme. Combined with keyboard navigation best practices, accessible dark mode implementation creates inclusive web experiences that serve all users.

CSS Custom Properties for Theme Management

Defining Color Tokens

The foundation of a maintainable dark mode implementation lies in CSS custom properties (variables). By centralizing color definitions, you create a single source of truth that simplifies both initial development and future updates. These variables establish the visual foundation for your light theme, where each token represents a semantic purpose rather than a specific color--this abstraction allows for seamless theme switching without modifying individual component styles. Similar to how CSS basic styling establishes foundational visual patterns, custom properties create systematic approaches to design tokens.

The example below shows semantic color tokens for background, text, accent colors, surface elements, and borders. Notice how the naming reflects the role of each color rather than its specific hue, making it easy to swap entire themes by redefining these values.

Dark Theme Color Definitions

For the dark theme, you redefine the same variables with appropriate values. The key insight is maintaining the semantic meaning of each token while adjusting the actual colors--background colors become darker, text becomes lighter, and accent colors are adjusted to maintain visibility against dark backgrounds. Using dark grays like #1a1a1a rather than pure black reduces eye strain and improves text rendering quality.

Component-Level Application

With variables defined, applying them to components becomes straightforward using the var() function. The transition property ensures smooth theme switching between light and dark modes, though you'll want to be selective about which properties animate to maintain performance. Components like cards, buttons, and form elements all reference the same semantic variables, ensuring consistent theming across your entire application.

System Preference Detection

Using prefers-color-scheme

The CSS prefers-color-scheme media query automatically detects the user's system-level theme preference and applies appropriate styles without requiring JavaScript, as documented in OpenReplay's dark mode tutorial. This media query supports two values: light for users who have set their system to light mode, and dark for those using dark mode. The implementation uses the :not([data-theme="light"]) selector to ensure that users who have explicitly chosen light mode aren't overridden by system preferences.

This approach provides automatic theme switching that respects the user's device settings, eliminating the need for manual toggling while still allowing users to override if desired. The browser handles detection efficiently at the CSS level, providing a seamless experience. Like animation direction techniques, system preference detection leverages modern CSS capabilities to create adaptive user experiences.

color-scheme Property

Modern CSS includes the color-scheme property, which tells the browser how to style native UI elements like scrollbars, form controls, and other browser-rendered components. By declaring color-scheme: light dark, you instruct browsers to adapt these elements to match the current theme automatically. This single declaration eliminates the need for custom styling of many common UI elements and ensures consistency between your application and the browser's native appearance, creating a more polished user experience, as covered in OpenReplay's CSS guide.

The light-dark() Function

Simplifying Color Definitions

For browsers that support it, the light-dark() function provides an elegant solution for theme-aware colors. This function automatically selects the appropriate color based on the active color scheme, eliminating the need for separate dark theme declarations, as explained in OpenReplay's dark mode guide. The browser handles all logic internally, reducing code complexity and maintenance overhead. The syntax is straightforward: pass the light color first, then the dark color, and the browser selects the appropriate value based on the active color-scheme.

This approach significantly reduces the amount of CSS needed for theming, as you no longer need to create separate blocks for light and dark variants. Each property declaration handles both themes in a single line, making your stylesheets more concise and easier to maintain.

Browser Support Considerations

While the light-dark() function offers significant advantages, browser support should guide implementation decisions. Currently, modern browsers including Chrome 120+, Firefox 120+, and Safari 17.2+ support this feature. For broader compatibility, maintain the traditional custom property approach as a fallback using the @supports at-rule, which checks whether the browser recognizes the function before applying it. This ensures older browsers still receive proper theming while modern browsers benefit from the simplified syntax.

Manual Theme Toggling

HTML Structure for Toggle Button

Implementing a manual theme toggle requires semantic HTML and appropriate accessibility attributes. The toggle button should be clearly labeled with an aria-label that describes its action, while aria-pressed communicates the current state to screen reader users, as recommended in Hoverify's accessibility guide. This accessibility-first approach ensures the toggle works for all users regardless of how they navigate.

JavaScript Toggle Implementation

The JavaScript implementation handles theme switching, preference persistence via localStorage, and system change detection. The getTheme() function checks for a saved user preference first, falling back to the system preference detection if no choice has been made. The setTheme() function applies the selected theme to the document and saves the choice to localStorage. When building interactive features like theme toggles, consider how they integrate with global variable patterns for state management across your application.

The updateToggleUI() function keeps the button's visual state synchronized with the current theme, updating both the displayed text and ARIA attributes. An event listener handles user clicks to toggle between themes, while a separate listener detects system preference changes for users who haven't explicitly chosen a theme. This implementation prioritizes user choice: explicitly saved preferences override system settings, while users who haven't made a choice see their system preference respected, as demonstrated in OpenReplay's toggle implementation guide.

Preventing Flash of Unstyled Content

Inline Script Approach

One of the most common issues with dark mode implementation is the "flash" that occurs when a page loads before JavaScript applies the saved theme. This flash happens when the page renders with the default light colors before your JavaScript runs and switches to the user's preferred dark theme, creating a jarring visual experience. The solution involves placing a small inline script immediately after the opening body tag that runs before the page paints, applying the correct theme immediately. For optimal implementation, integrate this with your node server setup without framework for server-side rendering capabilities.

The script checks localStorage for a saved theme preference, and if none exists, falls back to detecting the system preference. By running this script before any CSS or other JavaScript, the correct theme class is applied before the browser paints the page, completely eliminating the flash. This is essential for maintaining a professional appearance and smooth user experience.

Server-Side Consideration

For optimal performance and the cleanest implementation, consider applying the theme class on the server side based on the user's saved preference. This eliminates the need for any client-side JavaScript to handle the initial render, providing an instant theme experience for returning visitors without any flash whatsoever. Server-side rendering also improves perceived performance since the page arrives with the correct theme already applied.

Accessibility Requirements

Color Contrast Standards

Dark mode doesn't mean sacrificing readability. WCAG 2.1 guidelines specify minimum contrast ratios for text legibility: normal text requires a 4.5:1 minimum contrast ratio, while large text (18pt+ or 14pt+ bold) requires a 3:1 minimum contrast ratio, as outlined in Hoverify's WCAG contrast guidelines. UI components and graphical objects also require a 3:1 minimum contrast ratio. When choosing dark theme colors, test your combinations using browser DevTools or dedicated contrast checking tools to ensure clear visual hierarchy and text legibility in both themes.

Keyboard Navigation

The theme toggle must be fully keyboard accessible with visible focus states. The :focus-visible pseudo-class provides a way to show focus indicators only when navigating by keyboard, maintaining a clean appearance for mouse users while ensuring accessibility for keyboard users. Ensure the toggle has sufficient visual indication when focused, and that the focus order in your document makes logical sense. Accessible interactions like this complement other accessibility-focused techniques for inclusive design.

Screen Reader Considerations

Beyond the aria-label and aria-pressed attributes, consider how theme changes are announced to screen reader users. For significant theme changes, you might want to announce the change using a live region with aria-live="polite", allowing screen reader users to understand when the theme has been switched. This creates a more inclusive experience for all users.

Common Implementation Mistakes

Avoid filter: invert()

One of the most common mistakes is using filter: invert(1) to create dark mode. This approach inverts all colors indiscriminately, including images, icons, and media content, resulting in unpredictable and often unacceptable visual results. Images appear with inverted colors, transparent graphics become difficult to see against dark backgrounds, and the overall effect is unprofessional. Proper theming requires defining appropriate dark mode colors for each element rather than relying on CSS filters.

Avoid Pure Black Backgrounds

Pure black backgrounds (#000000) can cause eye strain and create issues with text rendering. Text can appear to "smear" when scrolling on some displays, pure black creates harsh contrast that tires the eyes over extended reading sessions, and white text on pure black can cause halation effects. Instead, use dark grays like #1a1a1a or #121212 that maintain the dark theme aesthetic while reducing strain and improving text rendering quality.

Avoid JavaScript-Only Implementations

Relying solely on JavaScript without CSS fallbacks creates fragile implementations. Users with JavaScript disabled get broken theming, initial render may show incorrect colors before scripts execute, and performance suffers from complex JavaScript handling. Always ensure your CSS provides a functional baseline with automatic system preference detection, with JavaScript enhancing the experience through manual toggling and persistence. Following these best practices for CSS implementation ensures robust, maintainable code.

Performance Considerations

Minimize Transitions

While smooth theme transitions enhance user experience, animating too many properties can cause performance issues. Limit transitions to only background-color and color, which don't trigger layout recalculations. Avoid transitioning properties like margin, padding, or dimensions that would cause the browser to recalculate layout. A transition duration of 0.3 seconds provides a smooth feel without noticeable performance impact on most devices. Optimizing transitions works hand-in-hand with rotateX animations and other CSS transforms for smooth, performant animations.

Optimize for Paint Performance

Theme changes that only affect colors don't trigger layout recalculations, but they do trigger repaints. For complex pages with many elements using theme variables, test performance on lower-powered devices to ensure smooth transitions. Consider reducing the number of elements that transition simultaneously, and use CSS custom properties strategically to minimize the scope of changes.

Critical CSS Strategy

For optimal initial load performance, include essential theme styles in your critical CSS. This ensures the page appears correctly even before the full stylesheet loads, eliminating the need for theme application scripts and providing an instant visual experience for users.

Summary

Implementing dark mode with CSS requires attention to several key areas: semantic CSS custom properties for maintainable theming, proper system preference detection with prefers-color-scheme, user-controlled toggling with localStorage persistence, accessibility compliance with WCAG contrast ratios, and performance optimization to prevent theme flash.

The modern CSS features like color-scheme and light-dark() simplify implementation significantly, but graceful degradation with fallback strategies ensures broad browser compatibility. Focus on user preferences and accessibility to deliver an experience that works for everyone.

Key Takeaways:

• Use CSS custom properties for centralized, maintainable color management
• Leverage prefers-color-scheme for automatic system preference detection
• Implement manual toggling with localStorage persistence for user choice
• Maintain WCAG contrast ratios in both light and dark themes
• Prevent flash of unstyled content with inline scripts before the body
• Test across devices and browsers for consistent experience

Ready to implement dark mode on your website? Our team at Digital Thrive specializes in creating performant, accessible web experiences with modern CSS techniques. Contact us to discuss how we can help build a polished, user-friendly dark mode implementation for your project.

Sources

1. Hoverify: Dark Mode Implementation with Tailwind CSS - Comprehensive guide covering dark mode configuration, accessibility standards, and WCAG contrast requirements
2. OpenReplay: How to Build a Dark Mode Toggle with CSS and JavaScript - Detailed tutorial on CSS custom properties, color-scheme property, light-dark() function, and preventing flash of unstyled content