Supporting Dark Mode in Your Web Content

Hello, I'm Tim Hatcher an engineer on the WebKit Team. I'm going to talk about Supporting Dark Mode in Web Content.

When macOS Mojave introduced Dark Mode, users and developers naturally began to ask about web content. Over the decades web content has traditionally been light in color leading to a very bright experience when mixed among newly Dark Mode aware apps.

The WebKit team has been working to standardize a way for developers to style web content for Dark Mode, which I'm happy to announce is available in Safari 12.1 on macOS Mojave and with iOS 13's system wide dark appearance, you will see the same Dark Mode styling for web content in Safari for iOS.

Throughout this video I'll be using Safari in my examples, but this support is not just available in Safari. It is also available in mail and in your app when showing content in web views.

There are three areas I want to cover in this video. One, general styling support for Dark Mode on the web. Two, some specific cases that apply to email messages. And, three, tools you can use to debug web content in Dark Mode.

Let's get started. I've been working on a new blog to document some recent trips I've taken around California.

While designing the site to be responsive for mobile and desktop visitors, this would be a good time to add support for Dark Mode. Dark mode can be viewed as a progression of responsive web design, another way to adapt to the circumstances of the device. It is important to note that Safari and WebKit will not auto darken your content. As the web developer, you are in control of how your content will appear to users using the dark system appearance. Let's take a look at how we can transform this light page design into a Dark Mode ready site. The main way to signal that your content supports Dark Mode is to adopt the new color scheme style property currently being specified for inclusion in the CSS standard. Specifying the values light and dark on the root element lets the rendering engine known both modes are supported by the document. This changes the default text and background colors of the page to match the current system appearance, standard form controls, scrollbars and other named system colors also change their look automatically.

Let's take a look at how adding that property to my blog affected things.

You can see the background color changed from white to black and most of my text completely disappeared into the black background; that was not what I was expecting. Let's take a look at some of the style rules for this page to see what is happening.

Here are the main style rules for the affected areas of the page.

For the text that disappeared the black was being set as the text color on the body. I also have a dark gray text color for the level 1 headings, which doesn't have a high enough contrast with the black background. By default, the text color of the body will be black and light mode.

Since that is what I wanted on this page I can just delete the color property override from my style sheet. Now that I'm using the color scheme property, the default text and background color will both automatically change to the Dark Mode values. For the other colors in my style sheet that I want to keep, I can use something called CSS custom properties otherwise known as CSS variables to centrally define them for use throughout my site style sheets. Using CSS variables makes it very easy to later adapt the style sheet for Dark Mode. Let's see how that will work.

We simply take the color values and move them to a central place like the root element rule we added for the color scheme earlier.

For these colors we define a variable name signified by a double hyphen prefix.

Now we can return to the original style rules where I am still using the static color values and change them to use the variables we defined referencing them by name using the VAR function which looks like this. This style sheet is now ready to support a dark color scheme.

Like responsive design breakpoints for different device widths, we can use a media query to conditionalize for Dark Mode. Specifically, if the user currently prefers a dark color scheme.

We can override the same CSS variables we defined earlier for light mode with Dark Mode appropriate color values. Now let's take a look at what the page looks like with these changes applied. We go from this where we only added the color scheme property to this where the text and header colors properly adapt to the dark appearance, but what about images? Like the hero picture here of the Mojave Desert.

The Mojave Desert image is included by an image element that is sourcing a JPEG on my server. We can easily adapt this code using another responsive design technique.

Specifically, the picture element, which is a great way to source multiple versions of an image based on various device characteristics using the same media queries. Here I specify an alternate image of the Mojave Desert at night using the same media query that was used earlier for the Dark Mode colors I can conditionally load a night image for users that prefer a dark color scheme. So we go from this where I was using one image for both color schemes to this where the desert image is adapted to the dark appearance and now the site is ready for both dark and light appearances.

To recap you want to use the new color scheme property to declare support for light and Dark Modes. This informs the rendering engine what color schemes your content was designed for so it can adapt the default colors and controls to match.

When the default colors are not enough, use the prefers-color-scheme media query for custom values.

You can use the same media query along with other responsive images in the picture element for Dark Mode ready sources and consider using CSS variables when adopting color schemes. It will be easier to maintain both appearance modes across your content.

That brings us to Dark Mode and email messages.

Just like mail in macOS Mohave simple email messages composed directly in mail on iOS 13 are ready to go in both light and dark appearances even if they include in-line image attachments like you see here. This is the case because of mail's auto darkening transformations that get applied to these simple email messages.

However, if you are an email template designer creating designs for a campaign that includes remotely loaded images, you will need to adopt the same styling techniques I covered earlier for web content. Without adopting the color scheme property mail will display your email message in the light appearance and will not employ any auto darkening transformations that simple email messages receive.

Here is the same email message with Dark Mode styling including the color scheme declaration. It is now perfectly adapted to the dark system appearance.

To recap simple email messages will auto darken even if they include in-line image attachments and rich email messages with remote images like custom email marketing campaigns will use the light color scheme by default. You can declare support for the dark color scheme in your marketing email messages and use the media query for custom color and image customizations.

Now let's talk about tools to debug Dark Mode content specifically Web Inspector.

In macOS, we added the dark appearance to Web Inspector when your system is in Dark Mode. This was a very popular request from web developers, and I'm very happy we have it now.

Not only did we add the dark appearance there are a couple tools to help you debug your own content in Dark Mode. The first is a new color scheme toggle in the elements tab that will change the page appearance without requiring you to toggle the entire system appearance every time. So if you like using Dark Mode, you can quickly test how your pages will look in the light appearance with this button.

Like before the style sidebar shows any rules that match for the selected element including any media queries. In this case, you can see the prefers color scheme media query definitions of color variables on the WebKit.org site. And that is Dark Mode and Web Inspector. Check out some of the other Safari and WebKit sessions for details about other great new features in Web Inspector for Safari 13. In summary, remember that web pages and rich email messages need to opt into Dark Mode. Safari and WebKit will not auto darken your content. For simple email messages you don't have to worry. Mail darkens them to match the system appearance automatically and now you can use Web Inspector to test your content in light and Dark Modes with the new color scheme toggle in the elements tab. I look forward to seeing what you will do with this support and how your sites and apps will look in Dark Mode on Mac and iOS.