Proposal: A Color-Theme Media Query and System Colors

I think we will design more visually comfortable and seamless websites and webapps for people once we have access to their preferred system color theme, and once we have access to certain system colors affected by those preferences.

When I sit down at my computer in a comfortably-lit environment, I prefer the less glaring appearance of a dark color scheme. Other times I want a dark palette just because it’s more relaxing to me, and it helps me focus. Alternatively, when I feel a need to energize myself, I prefer light tones. Or maybe I’m just outside and need more contrast. For these varied reasons, I’ve appreciated browser extensions like Stylus and Dark Mode, and I’m especially excited for “Dark Modes” in Android, Linux, Windows, and now MacOS. I love having this kind of control

As a web citizen and developer, I will thrive with these same choices on the web. I think this is why content-focused sites like Reddit and Twitter already offer Night Modes. I want this, and I want to offer this to my users.

I’m reminded of how @media (min-width) turned layout into an enhancement at a time when most sites and site prototyping apps insisted upon a fixed width. Responsive layouts were a paradigm shift. Forcing responsive layouts upon brands and at scale seemed impractical if not impossible, but here we are — we learned, and now we thrive. I foresee the same excitement, resistance, and potential now for color-responsive websites and webapps.

I propose we access to the user’s system color theme with a media query:

/* define colors when the system color theme is light (a light background with dark text) */
@media (color-theme: light) {
  html { background: #fff; color: #000 }
  a { color: #0000d6 }

/* define colors when the system color theme is dark (a dark background with light text) */
@media (color-theme: dark) {
  html { background: #000; color: #fff }
  a { color: #00c0ff }

Now, alongside a color-theme media query, I propose we expose certain system colors as new color keywords or as env() values. This would be immediately useful for coloring simple websites and form controls to match the system appearance, similar to what we get with the system-ui font.

:root {
  background-color: system-background-color;
  color: system-text-color;
  font-family: system-ui;

a {
  color: system-link-color;

Adding these features to CSS will require changes to CSS Media Queries and CSS Color. Would anyone help me?

I’ve made a pull request to change CSS Media Queries here: *

And here is the issue I filed for this with the CSSWG:

Finally, let me emphasize that my color preference is unique from my lighting conditions or accessibility enhancements. While my color theme may be influenced by lighting conditions and accessibility needs, my preference wouldn’t necessarily be overruled by them.

The choice of whether to enable a light or dark appearance is an aesthetic one for most users, and might not relate to ambient lighting conditions. — AppKit: Supporting Dark Mode In Your Interface

So, would you help me write up these features? Do you have any objections or concerns?


CSS 2 offered system keywords in 1998 (, along with support for system fonts, and it has been retained by browsers even though it was deprecated in CSS 3 (

Using keywords is also a best practice in many cases when supporting Windows High Contrast Mode ( so I expect Edge to continue to support them.

So I think your suggestion has two key parts:

  1. Get the spec to de-deprecate color keywords (so browsers might continue to support them),

  2. Work with operating systems or browsers (who do have light/dark themes already) to clearly define themes as one or the other, and expose that information.

Am I reading this right?

You are reading it correctly. But, de-deprecating the old color keywords doesn’t help the situation too much. What is being asked for is to tell based on the environment if the user has their desktop set to light or dark mode. The site can then adapt the display based on that. Since we can’t check for comparison of those system keywords, they won’t help too much towards the goal desired here.

I believe option 2 is what this discussion thread was started to achieve in the first place.

Something similar just shipped in Safari for macOS Mojave’s new Dark Mode:

@media (prefers-dark-interface) { /* … */ }

This might end up the standard, from iOS dominance.

@Tigt, that dark mode media query did not ship in any public way. It’s a private property, which may only be available to Xcode apps. I think folks started tweeting about it before testing it, and those tweets were far more popular and spreading than their corrections.

I directed Apple/WebKit developers chiming in on those threads to the CSSWG thread. I don’t know if any of them intend to contribute to the conversation, but they’re invited. And if they do scan the thread, then they can address questions presented by CSSWG folks and other implementors, at least internally.

Ah, wonderful. Thank you for the proper diligence!

To conclude this thread, styling for the operating system’s color scheme is now possible. There is a draft specification and the feature is in the technology preview of Safari 12.1.

@media (prefers-color-scheme: light) {
  html { background: #fff; color: #000 }
  a { color: #0000d6 }

@media (prefers-color-scheme: dark) {
  html { background: #000; color: #fff }
  a { color: #00c0ff }

You could use this along with Custom Properties to create your own custom color schemes.

On, I made it so that you get a unique color scheme based on this query (where it’s supported) but you can also override it yourself. I polyfill it for non-supporting browsers using css-prefers-color-scheme.

Thanks for sharing my enthusiasm!

1 Like

It’s a little strange and jarring that Firefox doesn’t tell websites to use a dark theme when you’ve gone into customise and enabled the dark theme. Developers working on Firefox have said that it is this way because prefers-color-scheme is designed to detect the system scheme. Could something be done about this? Microsoft Edge Insider also lets users enable dark theme manually.

I think that’s It’s not a hard change to make but it seems a bit contingent. You’re welcome to add to the discussion there.

There’s also been talk of adding explicit preferences for that (there is a hidden preference, ui.systemUsesDarkTheme), but exposing those in about:preferences or what not is not a decision that I can make myself :slight_smile:

Anyhow that is something to discuss in the Firefox bug tracker I guess.

I came from there.

The contention that enabling the dark theme within Firefox should tell sites to use a dark theme is that it would work on Linux distros/W7/W8/older versions. It would also match Windows 10 quite a bit as many apps allow you to enable the dark theme for individual apps.

The other argument’s only reason is that the spec does not support it. Kristoffer makes a good point in having a dark UI and light websites… This could be solved by a checkbox in the customise menu but I really do not think Mozilla would allow that as it’s not specified.

What makes you think the spec doesn’t support that? I was going to file a spec issue but says:

The method by which the user expresses their preference can vary. It might be a system-wide setting exposed by the Operating System, or a setting controlled by the User Agent.

It seems like the selected theme may qualify as “a setting controlled by the User Agent” :slight_smile: