Repository navigation
Description
Proposal
Authors should be able to style their content taking into account the users's preferred system-level color scheme (e.g. for dark mode on macOS Mojave, or Microsoft's high-contrast mode). This would allow, for example, a page to express the fact that it has a "dark mode", which would be displayed to users whose system preference is to use a dark-mode interface. Authors would use this new property in conjunction with the prefers-color-scheme media query.
Some UAs may also wish to apply automatic presentational transformations to web content (auto-darkening, or conversion into a high-contrast mode). The functionality described below allows a page to opt out of this UA-applied transformation.
Meta tag
We think adding a new meta tag is necessary so that UAs know early in parsing which color scheme is to be used, since this may impact the default appearance of the view containing the web content, and we wish to avoid flashes caused by delayed switches between color schemes.
The meta tag syntax is:
<meta name="supported-color-schemes" content="[light? || dark? || <ident>?]* || only?">
"" (empty string) (the default)—the UA may choose to transform the content to match the user's preference.
light dark—the UA will choose the light or dark theme to match the user's preference. If the user's preference does not match something in the list, the UA is allowed to apply transformations to the content (e.g. apply high-contrast).
only—synonym for light only; the UA will only ever render the content in the light color scheme, and never apply transformations[1].
light dark only—the UA will choose the first of the listed schemes that it supports taking user preference into account, and never apply transformations[1].
Custom scheme, like hi-contrast only—if the UA doesn't support hi-contrast it's allowed to fall back to its default rendering light, and will never apply transformations.
Note: <ident> is present for compatibility; some UAs may support color schemes in addition to light and dark, and the including of unrecognized schemes should not break parsing.
must not be “only”
Note: Maybe the meta tag should be specified outside of CSS.
[1] UAs are allowed to apply minimal transformations, for example making the root background transparent, but not change the overall appearance of the content.
CSS Property
supported-color-schemes: [light? || dark? || <ident>?]* || only?
Inherited: yes
Initial value: light
The CSS property has the same behavior as the meta tag, and allows authors to style sub-sections of content with a different color theme.
How the color scheme affects rendering
The UA may take the chosen color scheme into account when rendering the default page background, form controls, the default selection color, and other UA-controlled UI like misspelling underlines.
Interaction with the media query
The media query always matches the user preference. Authors should avoid styling content for the dark mode if they don't claim to support it in the meta tag.
Issue: Maybe in “non-only” mode the media query should reflect the scheme the UA is converting to?
Activity
fantasai commentedon Nov 15, 2018
Have you considered just re-using the Alternate Style Sheets mechanism from HTML per http://www.idpf.org/epub/altss-tags/#app-night-version-style-set-tags ?
rcabanier commentedon Dec 11, 2018
@fantasai that proposal will suffer from the problem that the style resolution happens after the document is already displayed.
This will result in a "flash" of the default styling which is not desirable.
rcabanier commentedon Dec 11, 2018
I think dark mode will need a different default UA stylesheet. For instance, the default document color could be transparent or black and default text color white.
tomhodgins commentedon Dec 11, 2018
I've thought a little bit about what would be required for a
dark-mode.css, and it seems that since chromium, gecko, and webkit all have slightly differenthtml.cssuser-agent stylesheets, to do a 'dark mode' base CSS stylesheet properly you'd probably need to create a new stylesheet that had light-on-dark default colors, and that included rules from all three user-agent stylesheets to make sure it was looking the same in all browsers. The resulting stylesheet would be big, and probably pretty ugly 😆I'm not sure that just one browser alone could implement a 'dark-mode.css' stylesheet that would be helpful for CSS authors to develop on top of if it wasn't necessarily catching every default style that another browser's user-agent stylesheet was setting.
If anybody is interested in making some kind of
dark-mode.cssbase stylesheet that CSS authors can build dark themes on top, please ping me. I'm interested in helping to assemble something like this, but haven't gotten around to starting that yet!xeenon commentedon Dec 11, 2018
Note that WebKit solves some of the complexity of dark and light mode colors by having special handling of CSS named colors. The named color can resolve to different values, depending on what mode you are in — like
buttonTextis dark in light mode, and white in dark mode. This proposal helps us know if the page (or DOM tree) expects those named colors and form controls to have different rendering, and not break the web by changing them on unsuspecting content.So our
html.cssis actually pretty much the same as it was before dark mode, with just some tweaks to use more named colors instead of hardcoded color values.rcabanier commentedon Dec 12, 2018
Is this something that can be put in a spec? Does CSS use named colors for default styles?
For the magic leap use case, we'd also like to have the color of the root element to be transparent by default instead of white (or black in dark mode)
phistuck commentedon Jan 29, 2019
Any reason not to support this in response headers as well?
rcabanier commentedon Jan 29, 2019
Could you elaborate what the use case of these headers would be?
The proposal for a meta tag is that it is parsed before the document is drawn which avoids the flash of white.
phistuck commentedon Jan 30, 2019
You have a few meta tags that should/must be served in the first packet of the response body, like
charset,viewportand a few more I do not recall right now. A meta tag is lengthier than a header. A header is received before the body packet (or sometimes with the first body packet?). The earlier you have this information, the earlier you can use it. Also, sometimes supported color schemes can be applied site-wide, so a global header would make it easier to apply everywhere, by a load balancer/reverse proxy/front end servers, without messing with the body.phistuck commentedon Jan 30, 2019
Sorry, the "few meta tags" point is that the more meta tags of those kinds (the "put it as early as possible" kind) pile up, the harder it gets to have them as early as required. Headers are shorter in nature and are received earlier than any response body (not trailing headers, obviously).
MatsPalmgren commentedon Feb 6, 2019
Hmm, the proposed feature seems backwards to me. A site shouldn't decide what theme the user should see. The preferred theme is entirely a user preference and the site should accommodate whatever theme the user has chosen, not the other way around.
rcabanier commentedon Feb 6, 2019
@MatsPalmgren this isn't about the site deciding the theme.
This feature is for users that already specified that they want to see a dark theme. Now a site can indicate that it will look ok to render it in a dark mode.
Without this feature, a UA wouldn't know if it can do so without affecting the usability of the page.
MatsPalmgren commentedon Feb 6, 2019
@rcabanier That's not how I understand this feature. So, if I'm using dark theme and a web page says
supported-color-schemes: light- what should the UA do in that situation exactly?rcabanier commentedon Feb 6, 2019
It will render the content in a light theme. It won't switch the whole browser.
14 remaining items
tomayac commentedon Apr 3, 2019
I think what this meta tag does gets pretty clear at the example of WebKit's user-agent stylesheet (do a full text search for "dark").
To illustrate, here's one such CSS rule (using the
:matchespseudo class and WebKit-internal variables like-apple-system-control-backgroundas well as WebKit-internal preprocessor directives):So if combined with
only, the meta tag allows a page to opt out of this UA-applied transformation.phistuck commentedon Apr 3, 2019
@tomayac - I would think it allows a page to opt into, not out of the user agent applied transformation. I mean, by default, the web did not intend dark mode controls. So this should remain the default for backward compatibility. If the user indicates it supports dark mode, then it opts into this transformation.
Anyway, @aaaxx - since a media query for dark mode is also planned, you could use it at the
<linklevel -(Note - this is pseudo-code, I do not remember if this is the exact syntax)
tomayac commentedon Apr 3, 2019
@phistuck I have clarified my comment:
phistuck commentedon Apr 3, 2019
@tomayac - oh, to opt out of light mode transformation (since dark is opt-in by default), right?
tomayac commentedon Apr 3, 2019
@phistuck Both actually the way I read it:
phistuck commentedon Apr 3, 2019
@tomayac - well, that does not make a lot of sense... "I support dark mode colors, so do not transform the page to have dark mode colors". Right?
phistuck commentedon Apr 3, 2019
@tomayac - I see now. I re-read. Well, "only" is a bad keyword for this functionality. I would prefer "no-transformation" or something. :( I am not sure what is the use case for this keyword.
tomayac commentedon Apr 3, 2019
I've tried to summarize this proposal in an article. Feedback/comments/corrections welcome.
lilles commentedon Apr 4, 2019
Since the META tag belongs in HTML, I've filed whatwg/html#4504 separately.
heycam commentedon Sep 13, 2019
Since the
<meta>keyword is now in css-color-adjust-1, can this issue be closed?lilles commentedon Oct 11, 2019
Yes.
Add 'color-scheme: light dark' to root.