Color Modes & Themes #3807

alanbsmith · 2026-03-03T13:46:26Z

alanbsmith
Mar 3, 2026
Maintainer

Color Modes & Themes

a general introduction and suggested implementation

Prior Art

Much of what is described below is heavily informed by GitHub’s theming functionality, which I consider to be best-in-class. They support system, light, and dark modes. They also currently support seven color themes, four of which are tailored for colorblindness, and they provide a high-contrast toggle for light and dark modes. If you have a GitHub account, and you’d like to investigate further, you can control them in your settings.

Overview

This guide provides a basic understanding of color modes and themes, how they work together, and how they are applied. This is intended for any technologist, so some information may seem introductory. It also covers details on a web implementation to ground the material a bit further. If you’re not interested in reading code snippets, you should still be able to benefit from the higher-level notes. If you prefer hands-on learning by interacting with an interface and pushing buttons, you can poke around at this Codepen prototype.

While color modes and themes are largely about aesthetic and personalization, the most important goals are to provide a uniform experience that is:

tailored to the user’s preferences
inclusive of everyone
reflective of our customer’s brand

Color Modes vs Themes

Before jumping into the details, It’s worth taking a moment to describe the difference between “color modes” and “themes.” While the terms are often used interchangeably, they have important distinctions between them.

A color mode is a modality that allows users to control which themes are available and applied to their UI. Modes can be activated and deactivated, and there can only be one active color mode. For example, it is not possible to have both light and dark modes active at the same time.

A color theme defines a specific color palette or collection of palettes. It sets variables and overrides others to apply the theme to the interface. Themes can be independent of color modes, but they are often tailored to reflect the particular active mode. For example, a dark theme defines a set of variables that are rendered when activating dark mode. Themes can serve a variety of purposes from aesthetic, to accessibility, to brand alignment. They can be layered, and often multiple themes are applied at once. Their layer structure informs how these themes are applied to the interface.

Color Modes

Color modes allow users to control how themes are expressed. The three most common color modes are dark, light, and system (sometimes called “automatic”).

Dark mode activates only dark-related themes can be applied to the UI.
Light mode activates only light-related themes can be applied to the UI.
System mode activates whichever mode is currently active for the operating system.
- Depending on the system settings, this could be always light, always dark, or switch based on the time of day.

Web Implementation

The best method for toggling color modes is through a single, top-level variable. This creates a single source of truth that is:

accessible to any UI elements rendered further down the DOM structure
easily referenced in the CSS cascade.
easily toggled from anywhere on the page

A common best practice is to set a data attribute on the root <html>element. In the code example below, we’re using data-color-mode.

<!-- dark mode -->
<html data-color-mode="dark">
<!-- light mode -->
<html data-color-mode="dark">
<!-- system (auto) mode -->
<html data-color-mode="auto">

These modes can then be referenced in CSS. Light and dark modes largely work the same. The color-scheme CSS property tells the browser how to align styles with the current active mode. Note that there are no particular CSS variables being defined for any mode – those are defined in the color themes.

/* Set styles for light mode */
:root[data-color-mode="light"] {
  color-scheme: light;
}

/* Set styles for dark mode */
:root[data-color-mode="dark"] {
  color-scheme: dark;
}

System mode works a bit differently in CSS, as it requires a media query, prefers-color-scheme, to reflect the operating system’s current active theme.

/* Set styles for system light mode */
@media (prefers-color-scheme: light) {
  /* Define light themes and styles go here */
}

/* Set styles for system dark mode */
@media (prefers-color-scheme: dark) {
  /* Define dark themes and styles go here */
}

Detecting the current color mode in JavaScript is also pretty straightforward. This would probably look different in React, but this is how we could do it with plain JavaScript.

function getCurrentColorMode() {
  // Get the root element (`<html>`)
  const rootElement = document.querySelector('[data-color-mode]');
  // Fail early in case the element isn't found.
  if (!rootElement) {
    console.warn('Error: No element with [data-color-mode] was found.');
	return;
  }
  // Get the value of the data attribute
  const colorMode = rootElement.getAttribute('[data-color-mode]');
  // For system mode, we need to check to see what the OS is using
  if (colorMode === 'auto') {
    // This will only ever return `true` or `false`
    return window.matchMedia('prefers-color-scheme: dark').matches ? 'dark' : 'light';
  } else {
    return colorMode;
  }
}

We can also toggle the current color mode with plain JavaScript as well.

function setCurrentColorMode(mode) {
  // Get the root element (`<html>`)
  const rootElement = document.querySelector('[data-color-mode]');
  // Fail early in case the element isn't found
  if (!rootElement) {
    console.warn('Error: No element with [data-color-mode] was found.');
	return;
  }
  // Update the color mode on the root element
  rootElement.setAttribute('data-color-mode', mode);
}
// Set the current color mode to 'dark'
getCurrentColorMode('dark');

Color Themes

As stated above, a color theme defines a specific color palette or collection of palettes that are applied to the UI. These themes are applied to the interface when a particular mode is activated and the theme is selected.

You might be wondering: Why don’t we allow the color mode to define the color palettes instead of using themes? We certainly could! From an implementation standpoint, there’s no technical reason why we couldn’t go that route. However, it comes with a major tradeoff: If you ever want to have multiple light or dark palettes, and your logic is tied to color modes instead of themes, you have quite a lot of untangling to do. It’s quite common for interfaces to have a dark and soft dark themes to accommodate different aesthetics and user preferences. Separating modes and themes allows us to keep that flexibility at little-to-no complexity cost.

Below, we’ll look at each theme layer and discuss how they work together.

Theme Layers

In the initial overview, we mentioned that themes can be layered. The number of layers and how they override is dependent on the application’s product requirements. Most modern interfaces have at least a single base layer to toggle aesthetic color themes such as light, dark, and dimmed or soft dark. Other interfaces with more advanced theming provide a secondary theme layer which is generally used for enhanced accessibility. Still other interfaces provide a separate theme layer for private labeling or branding to align it with the tenant’s brand, such as Workday, Nike, and Apple.

Base Layer Themes

Base layer color themes, such as light, dark, and dimmed provide the overall foundation for the interface. They touch every part of our interfaces: surfaces, type, icons, buttons, and inputs. They are the primer coat to all secondary and tertiary themes that are layered on top.

It’s important to consider how these themes interact with their corresponding color modes. While the themes define variables used in their palettes, they are not applied until their associated mode is active. To provide multiple themes for any given mode, we need a separate mechanism to set and update them in code.

Web Implementation

To implement this in HTML, we’ll use two separate data attributes, data-color-dark-theme and data-color-light-theme on the root <html> element. This allows us to always track which theme should be rendered whether the data-color-mode is toggled to dark, light, or auto.

<!-- This UI is in dark mode and would render the dark theme -->
<html data-color-mode="dark" data-color-dark-theme="dark" data-color-light-theme="light">

To support this in CSS, we’ll need to update our selectors to apply these base layer themes and define our CSS variables. This is pretty straight-forward for light and dark modes, but we’ll need to use the media query to prefers-color-scheme for system (auto) mode.

We’ll discuss this further in the Accessibility Layer Themes section, but one nice quality about these color theme selectors is they use * which fuzzy matches the values. This allows us to combine and layer themes using the same data attribute.

/* Define light theme when light mode is activated */
:root[data-color-mode="light"][data-color-light-theme*="light"] {
  /* Define CSS light mode CSS variables here */
}

/* Define dark theme when dark mode is activated */
:root[data-color-mode="dark"][data-color-light-theme*="dark"] {
  /* Define CSS dark mode CSS variables here */
}

/* Define the light theme for system-light mode */
@media (prefers-color-scheme: light) {
  :root[data-color-mode="auto"][data-color-light-theme*="light"] {
    /* Define CSS light mode CSS variables here */
  }
}

/* Define the dark theme for system-dark mode */
@media (prefers-color-scheme: dark) {
  :root[data-color-mode="auto"][data-color-light-theme*="dark"] {
    /* Define CSS dark mode CSS variables here */
  }
}

Toggling between these themes with JavaScript follows a similar pattern to our mode implementation. Again, this would likely look different as a React implementation, but this is a straightforward approach for plain JavaScript.

function setColorTheme(theme) {
  if (theme.startsWith('light') {
    const root = document.querySelector('data-color-light-theme');
    // Toggle the color theme
    root.setAttribute('data-color-light-theme', theme);
  } else if (theme.startsWith('dark') {
    const root = document.querySelector('data-color-dark-theme');
    // Toggle the color theme
    root.setAttribute('data-color-light-theme', theme);
  }
}
// Set the current color theme to 'dark'
setColorTheme('dark');

Accessibility Layer Themes

Accessibility themes are layered on top of the base themes. They generally will not be as expansive as our base layer and will instead target specific variables to update. For example, a protanopia theme might only need to update red color palettes. Or a high-contrast theme might only update borders, typography, and iconography. It’s also worth noting that we will need a separate expression of these themes for light and dark modes.

Web Implementation

To implement these layers in HTML, we can follow our existing data attribute pattern. You can see from the values how we’re layering on our accessible themes using the same data-color-dark-theme and data-color-light-theme attributes. This user has set their dark theme to be Dark + Protanopia + High Contrast and their light theme to Light + Protanopia.
That level of customization is really helpful for users with different visual capabilities.

<!-- This UI is in dark mode and would render the dark theme -->
<html data-color-mode="dark" data-color-dark-theme="dark-protanopia-high-contrast" data-color-light-theme="light-protanopia">

Similarly, in CSS, we can follow the pattern established in our previous implementation by modifying the color theme data attributes. Again, because we’re using the * fuzzy match selectors, we don’t need to have every combination of selectors listed out – only the ones we need to explicitly define.

:root[data-color-mode="light"][data-color-light-theme*="protanopia"] {
  /* Define light mode protanopia variables here */
}

:root[data-color-mode="light"][data-color-light-theme*="high-contrast"] {
  /* Define light mode high-contrast variables here */
}

:root[data-color-mode="dark"][data-color-dark-theme*="protanopia"] {
  /* Define dark mode protanopia variables here */
}

:root[data-color-mode="dark"][data-color-dark-theme*="high-contrast"] {
  /* Define dark mode high-contrast variables here */
}

And finally, to toggle with JavaScript, we can reuse our existing setColorTheme function.

//
setColorTheme('dark-protanopia-high-contrast');
setColorTheme('light-protanopia');

Brand Layer Themes

Tenant brand themes create another level of complexity because while we can know the default brand (Workday) ahead of time, we don’t necessarily know the name of the current tenant brand ahead of time. This means we need to control these styles separately and inject them when the application renders.

Note: While this is a third, distinct theme layer, a particular brand color theme should never create a less accessible experience for users. For example, brands with a red primary color such as Target, Twilio, or Airbnb should not have themes that create an inaccessible experience for users with protanopia. This is something we could handle in how we cascade our styles, or it could be something we allow tenants to configure at the top level.

Brands will need to have separate themes for light and dark modes. That is perhaps something we could adjust programmatically, but it might also be something brands want to configure on their own.

Web Implementation

To toggle brand-specific theming in HTML, we’ll need to create yet another data attribute that we can inject into the DOM.

<!-- This UI is in dark mode and would render the dark Workday theme -->
<html data-color-mode="dark" data-color-dark-theme="dark" data-color-light-theme="light" data-brand-theme="workday">

Our CSS would also follow a similar pattern as our other themes. Again, because we don’t know these themes ahead of time, these styles would need to be created and injected dynamically.

:root[data-color-mode="light"][data-brand-theme="workday"] {
  /* Define Workday-specific brand styles for light mode. */
}

:root[data-color-mode="dark"][data-brand-theme="workday"] {
  /* Define Workday-specific brand styles for light mode. */
}

We might need a new JavaScript function to handle toggling the brand theme, but it would look similar to what we’ve done previously.

function setCurrentBrandTheme(brand) {
  const rootElement = document.querySelector('html');
  if (!rootElement) {
    console.warn('Error: No HTML element found');
	return;
  }
  return rootElement.setAttribute('data-brand-theme', brand)
}

Conclusion

Color modes and themes work together to create flexible, personalized, and inclusive user interfaces. By separating the concerns of modes (light, dark, and system) from themes (base, accessibility, and brand layers), we can build systems that are both composable and maintainable — making it easy to add new palettes or override specific variables without untangling tightly coupled logic. A consistent implementation pattern using HTML data attributes, CSS custom properties, and simple JavaScript utilities provides a reliable single source of truth that scales gracefully across every layer of theming. When done well, this system ensures every user — regardless of visual ability, preference, or the brand they're interacting with — has a coherent and accessible experience.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Color Modes & Themes #3807

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Color Modes & Themes #3807

Uh oh!

alanbsmith Mar 3, 2026 Maintainer

Color Modes & Themes

Table of Contents

Prior Art

Overview

Color Modes vs Themes

Color Modes

Web Implementation

Color Themes

Theme Layers

Base Layer Themes

Web Implementation

Accessibility Layer Themes

Web Implementation

Brand Layer Themes

Web Implementation

Conclusion

Replies: 0 comments

alanbsmith
Mar 3, 2026
Maintainer