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!