Photo

Hi, I'm Aaron.

Mountains

Code is Sisyphean

Adding accessible Dark Mode to your site with prefers-color-scheme and CSS variables

Dark mode is about accessibility, not aesthetics

OK, it does have a sleek look to it, also. But this is an accessibility issue, primarily.

My eyes are pretty light sensitive. In most of the photos of me as a child, if it was taken outdoors, I was probably squinting. I can see pretty well in the dark, to where I don’t tend to turn lights on unless I need to read something.

Needless to say, when I see a website that is a sea of white with black text on it, especially if the text is small, this is often my experience:

My eyes. They burn.

Can’t I just turn the brightness of my monitor down? Sure, but that indirectly also reduces contrast, which makes it harder to read. This can be particularly challenging when the font is also small. This isn’t just inconvenient, it has caused physical pain (like when you look directly at a bright light), and has also induced headaches.

To be absolutely clear, I am not saying that the whole Internet needs to be made dark-mode. I am saying that the whole Internet needs to be adaptive to dark mode.

Most modern devices, including desktops, are capable of setting a color-scheme preference for light or dark mode.

Users think about dark mode at the operating-system level, not at the individual application level. Once they’ve set their device to dark mode in the system settings, they generally assume that all applications and websites will automatically display in dark mode — that is, they basically expect to see a lot more black than white. They do not expect to have to enable dark mode within individual applications. (via NNG)

Thankfully, there is a fairly easy way to implement this, using CSS.

Prefers Color Scheme

The prefers-color-scheme media query is fully supported in all major browsers, presently. It is a CSS media query that works like this:

@media (prefers-color-scheme: dark) {
  /* styles to use if the user is in dark mode */
}
@media (prefers-color-scheme: light) {
  /* styles to use if the user is in light mode */
}

That’s it! You don’t have to add anything to your document templates, no javascript or anything else. This just works(*).

Just kidding, there’s a little more to do. Thankfully, this implementation is also still pretty smooth.

(* ok, so if your particular site does styling in your javascript, for example, or does not use traditional stylesheets for styling, it may be more complicated for you. But this is another reason why you should use conventional methods!)

CSS Variables for light and dark modes

What we want to do here is kind of like polymorphism, but in CSS. Modern CSS allows us to define CSS variables that we can then reuse. This does not require SASS/SCSS anymore, and is part of the CSS3 standard syntax.

They look are defined like this:

:root {
  --black: #000;
}

and are used like this:

body {
  background-color: var(--black);
}

We have to use the :root pseudo-selector because the variable definitions are technically style properties (custom properties) and need to be contained within a selector. Using :root makes them globally avaiable in your document.

The Labors

We’re going to approach this in a few phases. It shouldn’t take “very long”, but honestly this depends a lot on the complexity of your site and how you organized your CSS. I am a long-time SCSS user who uses variable names for most styles, so my CSS is organized very modularly.

  1. Gather all the colors you use
  2. Define them as CSS variables
  3. Define CSS variables for light mode
  4. Replace all colors with your new variables
  5. Define a dark-mode variant for those purposes

That’s it!

Part 1: Gathering your colors

OK so this can be a little time-consuming. The first thing you have to do is collect all of the colors you use. You can do this pretty quickly with a RegEx and RipGrep(*):

$ rg -o "#[a-fA-F0-9]{3,6}" _scss/ | uniq

_scss/base/_utilities.scss:#000
_scss/base/_utilities.scss:#666
_scss/base/_utilities.scss:#999
_scss/base/_utilities.scss:#333
_scss/base/_reset.scss:#ff0
_scss/base/_reset.scss:#000
_scss/base/_variables.scss:#e0e1e6
_scss/base/_variables.scss:#f8f3d2
// ...and so on...

Part 2: Define your CSS color variables

From this, you can copy and paste it directly into your CSS and trim it down to something that looks more like this:

:root {
  --color-black: #000;
  --color-gray: #666;
  --color-gray-light: #999;
  --color-gray-dark: #333;
  --color-yellow: #ff0;
  --color-silver: #e0e1e6;
  --color-cream: #f8f3d2;
  --color-dodger-blue: #1E90FF;
}

Note: if you are using darken() or lighten() (SCSS functions), or if you were defining your values using rgb() or rgba() or hsl() or hsla() you will need to search your CSS for those separately. I’ll leave that as an exercise to the reader.

For right now, the goal is to name the colors. If you need inspiration or are bad with color names, you can check the extended colors list or color names list. Or just make up your own.

Don’t use “primary-color”, “background”, etc. right now. That’s next. Just name the colors.

Part 3: Defining default usage (light mode)

We’re going to treat light mode as the default case here. The goal here is to define your purposeful uses for these colors.

Here’s a boilerplate example:

:root {
  /* color definitions, from above */

  /* Currently, the media query is commented out because we don't want to enable it quite yet */
  /* @media (prefers-color-scheme: light) { */
  --background-color: var(--color-silver);
  --text-color:       var(--color-black);
  --link-color:       var(--color-dodger-blue);
  --link-hover-color: var(--color-yellow);
  /* } */
}

Consider this a living list – you will likely need to add additional purposeful colors here.

Part 4: Replace your color variables with your purposeful variables

Re-using our ripgrep query from earlier:

$ rg "#[a-fA-F0-9]{3,6}" _scss/

_scss/base/_utilities.scss
15:    3px  3px 0 #000,
16:   -1px -1px 0 #000,
17:    1px -1px 0 #000,
18:   -1px  1px 0 #000,
19:    1px  1px 0 #000;
24:    3px  3px 0 #666,
25:    2px 3px 0 #999,
26:    5px 5px 0 #333;

_scss/base/_reset.scss
143:  background: #ff0;
144:  color: #000;
370:  border: 1px solid #1E90FF;

This gives you the filenames and line numbers of all of your colors. The job is now this process:

  1. Open the file and find the line number indicated by the report
  2. Find the corresponding CSS variable from the “purposeful” list you made in Part 3.
  3. If there is no good variable already defined, then consider the usage define a new one
  4. Repeat

For example, you’ll have something like this:

body {
  color: white;
  background-color: black;
}

and change it to:

body {
  color: var(--text-color);
  background-color: var(--background-color);
}

When you’re done, you should not see explicit color codes in the scan of your CSS. It should look something like this:

$ rg "#[a-fA-F0-9]{3,6}" _scss/
_scss/base/_variables.scss
19:    --border-color:      #e0e1e6;
20:    --smoke-color:       #fafafa;
26:    --bg-color:          #333;
29:    --border-color:      #e0e1e6;

$

Check your site in your development environment and make sure it looks the same, and that it loads correctly. If you’re using a CSS preprocessor that checks your syntax, it may give you helpful feedback if you have any errors.

Fix any errors, then continue.

Part 5: Define your dark mode variant

:root {
  /* color definitions, from above */

  /* OK, let's enable it! */
  @media (prefers-color-scheme: light) {
    --background-color: var(--color-silver);
    --text-color:       var(--color-black);
    --link-color:       var(--color-dodger-blue);
    --link-hover-color: var(--color-yellow);
  }
  @media (prefers-color-scheme: dark) {
    --background-color: var(--color-black);
    --text-color:       var(--color-silver);
    --link-color:       var(--color-yellow);
    --link-hover-color: var(--color-dodger-blue);
  }
}

This is the thing that does the thing.

So the way this works for a user that has set their device-level setting to Light Mode, is this:

Given this HTML:

<body>
  <p>Lorem ipsum dolor....</p>
</body>

The CSS that would style it:

body {
  color: var(--text-color);
  background-color: var(--background-color);
}

will consult the definitions for those variables:

@media (prefers-color-scheme: light) {
  --text-color: var(--color-black);
  --background-color: var(--color-white);
}

And you would see black text on a white foreground.

But if the user has their device-level settings set to Dark Mode, then it would instead use the other block:

@media (prefers-color-scheme: dark) {
  --text-color: var(--color-white);
  --background-color: var(--color-black);
}

They’ll see white text on a black background instead.

Success!

Final thoughts

If you want it to be toggleable, you can add that separately. But the point of this is to transparently adapt the display of your site to align with the preference of the user. The whole point of ubiquitous accessibility is that it fades into the background. You don’t have to make a big fanfare about offering dark mode, and ideally, your users realize, sometime after using the site “oh wait, it looks like they added dark mode!”

Using prefers-color-scheme with CSS variables is a compromise for maintainablility of development with providing support for users that have opted into having lower luminosity.

–

See also