|
| 1 | +<pre class='metadata'> |
| 2 | +Title: CSS Color Adjust Module Level 1 |
| 3 | +Shortname: css-color-adjust |
| 4 | +Level: 1 |
| 5 | +Status: ED |
| 6 | +Work Status: exploring |
| 7 | +Group: CSSWG |
| 8 | +ED: https://drafts.csswg.org/css-color-adjust-1/ |
| 9 | +Editor: Elika J. Etemad / fantasai, Invited Expert, http://fantasai.inkedblade.net/contact, w3cid 35400 |
| 10 | +Editor: Rossen Atanassov, Microsoft, ratan@microsoft.com, w3cid 49885 |
| 11 | +Editor: Rune Lillesveen, Google, futhark@google.com |
| 12 | +Editor: Tab Atkins Jr., Google, http://www.xanthir.com/contact/, w3cid 42199 |
| 13 | +Abstract: This module introduces a model and controls over automatic color adjustment by the user agent to handle user preferences, such as "Dark Mode", contrast adjustment, or specific desired color schemes. |
| 14 | +</pre> |
| 15 | + |
| 16 | +Introduction {#intro} |
| 17 | +===================== |
| 18 | + |
| 19 | + |
| 20 | + |
| 21 | + |
| 22 | +Preferred Color Schemes {#preferred} |
| 23 | +======================= |
| 24 | + |
| 25 | + Operating systems and user agents often give users |
| 26 | + the ability to choose their preferred color schemes |
| 27 | + for user interface elements. |
| 28 | + These are typically reflected in the user agent's rendering |
| 29 | + of its navigation interface as well as in-page interface elements |
| 30 | + such as form controls and scrollbars, |
| 31 | + and are expected to also be reflected |
| 32 | + in the values of the CSS system colors. |
| 33 | + |
| 34 | + Users on some systems can also indicate a preference |
| 35 | + in the color scheme of the pages they view, |
| 36 | + requesting that the author adapt the page to those color preferences. |
| 37 | + (It is not required to express a preference; |
| 38 | + users can have preferences for operating system interface colors |
| 39 | + that they do not want imposed on pages.) |
| 40 | + The most common preferences |
| 41 | + are a choice of “Light” vs “Dark” (or “Day Mode” vs “Night Mode”) color schemes, |
| 42 | + rendering things as mostly light- or dark-colored backgrounds, |
| 43 | + and with dark- or light-colored foregrounds (text, icons). |
| 44 | + This module, |
| 45 | + together with Media Queries Level 5, |
| 46 | + defines controls to enable color scheme negotiation |
| 47 | + for "light" and "dark" color schemes (and no preference). |
| 48 | + |
| 49 | + To enable pages to adapt to the user's preferred color scheme, |
| 50 | + user agents will match the '@media/prefers-color-scheme' media query |
| 51 | + to the user's preferred color scheme. |
| 52 | + See [[MEDIAQUERIES-5]]. |
| 53 | + |
| 54 | + Additionally, if the author has indicated that the page can support this color scheme |
| 55 | + (see 'color-scheme'), |
| 56 | + the user agent must match the following to the user's preferred color scheme: |
| 57 | + |
| 58 | + * the initial color of the background canvas <span class=issue>find what we name this in other specs</span>, |
| 59 | + the initial value of the '/color' property, |
| 60 | + and the [[css-color-4#system-colors|system colors]] |
| 61 | + * the default colors of scrollbars and other interaction UI |
| 62 | + * the default colors of form controls and other "specially-rendered" elements |
| 63 | + * the default colors of other browser-provided UI, such as "spellcheck" underlines |
| 64 | + |
| 65 | + User agents <em>may</em> support additional color schemes, |
| 66 | + however CSS does not support negotation of additional color schemes: |
| 67 | + user agents should pursue standardization of these schemes, |
| 68 | + so that '@media/prefers-color-scheme' and 'color-scheme' can reflect the additional values. |
| 69 | + |
| 70 | + Note: Aside from the small list of adjustments given above, |
| 71 | + user agents generally do not further adjust a page to match the user's preferred color scheme, |
| 72 | + because the chance of accidentally ruining a page is too high. |
| 73 | + However, when particular color choices are required by the user |
| 74 | + (for accessibility reasons, for example), |
| 75 | + more invasive changes might be applied; |
| 76 | + see [[#forced]]. |
| 77 | + |
| 78 | +Opting Out of a Preferred Color Scheme: the 'color-scheme' property {#color-scheme-prop} |
| 79 | +------------------------------------------------------------------- |
| 80 | + |
| 81 | + <pre class=propdef> |
| 82 | + Name: color-scheme |
| 83 | + Value: auto | only? && [ light | dark | <<custom-ident>> ]+ |
| 84 | + Initial: auto |
| 85 | + Applies to: all elements |
| 86 | + Inherited: yes |
| 87 | + Computed Value: the keyword ''auto'', or optional ''only'' keyword and ordered list of specified color scheme keywords, with any <<custom-ident>>s or repeated keywords dropped |
| 88 | + </pre> |
| 89 | + |
| 90 | + The 'color-scheme' property allows an element to indicate |
| 91 | + which color schemes it is comfortable being rendered with. |
| 92 | + These values are negotiated with the users preferences, |
| 93 | + resulting in a chosen color scheme |
| 94 | + that affects UI things such as |
| 95 | + the default colors of form controls and scrollbars |
| 96 | + as well as the used values of the CSS system colors. |
| 97 | + Its values are defined as follows: |
| 98 | + |
| 99 | + <dl dfn-type=value dfn-for=color-scheme> |
| 100 | + : <dfn>auto</dfn> |
| 101 | + :: Indicates that the element isn't aware of color schemes at all, |
| 102 | + and so the element should be rendered with the browser's default color scheme. |
| 103 | + |
| 104 | + : <dfn lt="light | dark">[ light | dark | <<custom-ident>> ]+</dfn> |
| 105 | + :: Indicates that the element is aware of and can handle the listed color schemes, |
| 106 | + and expresses an ordered preference between them. |
| 107 | + (See [[#color-scheme-processing]] for details on how this choice is resolved.) |
| 108 | + |
| 109 | + ''light'' represents a "light" color scheme, |
| 110 | + with light background colors and dark foreground colors. |
| 111 | + ''dark'' represents the opposite, |
| 112 | + with dark background colors and light foreground colors. |
| 113 | + |
| 114 | + Note: Providing both keywords indicates that the first scheme is preferred, |
| 115 | + but the second is also acceptable |
| 116 | + if the user prefers it instead. |
| 117 | + |
| 118 | + <<custom-ident>> values are meaningless, |
| 119 | + and exist only for future compatibility, |
| 120 | + so that future added color schemes do not invalidate the 'color-scheme' declaration |
| 121 | + in legacy user agents. |
| 122 | + User agents <em>must not</em> interpret any <<custom-ident>> values as having a meaning; |
| 123 | + any additional recognized color schemes |
| 124 | + must be explicitly added to this property’s grammar. |
| 125 | + To avoid confusion, |
| 126 | + authoring tutorials and references |
| 127 | + should omit it from their materials. |
| 128 | + |
| 129 | + Repeating a keyword, such as ''color-scheme: light light'', |
| 130 | + is valid but has no additional effect |
| 131 | + beyond what the first instance of the keyword provides. |
| 132 | + |
| 133 | + : <dfn lt=only>only?</dfn> |
| 134 | + :: If provided, |
| 135 | + ''only'' indicates that the element <em>must</em> be rendered with one of the specified color schemes, |
| 136 | + if possible, |
| 137 | + even if the user's preference is for a different color scheme. |
| 138 | + |
| 139 | + Authors <em>should not</em> use this value, |
| 140 | + and should instead ensure that their page renders well with whatever color scheme the user prefers |
| 141 | + (using the '@media/prefers-color-scheme' media query to adjust styles accordingly). |
| 142 | + This keyword is provided only for the rare cases where that might not be reasonably possible, |
| 143 | + and using a different color scheme would render the element difficult or impossible to use. |
| 144 | + |
| 145 | + Note that user agents are <strong>not required</strong> |
| 146 | + to support any particular color scheme, |
| 147 | + so using ''only'' to indicate a required color scheme |
| 148 | + is still not guaranteed to have any effect on the rendering of the element. |
| 149 | + </dl> |
| 150 | + |
| 151 | +Finding the Used Color Scheme {#color-scheme-processing} |
| 152 | +----------------------------- |
| 153 | + |
| 154 | + <div algorithm> |
| 155 | + To find the <dfn>used color scheme</dfn> for an element |el|: |
| 156 | + |
| 157 | + 1. Let |scheme| be the keyword matching '@media/prefers-color-scheme'. |
| 158 | + |
| 159 | + 2. If the computed value of 'color-scheme' on |el| |
| 160 | + contains |scheme|, |
| 161 | + return |scheme|. |
| 162 | + |
| 163 | + 3. If the computed value of 'color-scheme' on |el| contains the ''only'' keyword |
| 164 | + or |scheme| is <css>no-preference</css>, |
| 165 | + and at least one color scheme indicated in 'color-scheme' |
| 166 | + is supported by the user agent, |
| 167 | + return the first keyword, |
| 168 | + in specified order, |
| 169 | + that is supported by the user agent. |
| 170 | + |
| 171 | + 4. Otherwise, return null. |
| 172 | + </div> |
| 173 | + |
| 174 | + For each element, |
| 175 | + find the [=used color scheme=] for that element. |
| 176 | + If the [=used color scheme=] is <css>no-preference</css>, |
| 177 | + the element must be rendered with the user agent's default color scheme. |
| 178 | + (For Web compatibility, this should be a "light" color scheme.) |
| 179 | + Otherwise, |
| 180 | + the element must be rendered with the [=used color scheme=]. |
| 181 | + |
| 182 | + Note: This algorithm ensures that |
| 183 | + if the user prefers a non-default color scheme, |
| 184 | + it will only be used if the page claims to support it. |
| 185 | + This ensures that legacy pages, |
| 186 | + written before color scheme preferences were exposed, |
| 187 | + do not change behavior. |
| 188 | + |
| 189 | + For all elements, |
| 190 | + rendering with a color scheme should affect the colors used in all browser-provided UI for the element-- |
| 191 | + e.g. scrollbars, spellcheck underlines, form controls, etc.-- |
| 192 | + to match with the intent of the color scheme. |
| 193 | + |
| 194 | + For the root element of a page, |
| 195 | + rendering with a color scheme additionally must affect the background of the canvas, |
| 196 | + the initial value of the '/color' property, |
| 197 | + and the [[css-color-4#system-colors|system colors]], |
| 198 | + and should affect the page's scrollbars. |
| 199 | + |
| 200 | +The "color-scheme" <{meta}> value {#color-scheme-meta} |
| 201 | +--------------------------------- |
| 202 | + |
| 203 | + To aid user agents in rendering the page background with the desired color scheme immediately |
| 204 | + (rather than waiting for all CSS in the page to load), |
| 205 | + a 'color-scheme' value can also be provided in a <{meta}> element. |
| 206 | + |
| 207 | + If the <{meta/name}> attribute of a <{meta}> element |
| 208 | + is an [=ASCII case-insensitive=] match for the string "color-scheme", |
| 209 | + the value must be [=CSS/parsed=] against the 'color-scheme' grammar, |
| 210 | + and the result treated as a declaration of the 'color-scheme' property on the root element, |
| 211 | + as a [[css-cascade-4#preshint|non-CSS presentational hint]]. |
| 212 | + |
| 213 | + If there are multiple such <{meta}> elements, |
| 214 | + only the first such is honored. |
| 215 | + |
| 216 | + Issue(#3846): Or should we use some other rule? |
| 217 | + |
| 218 | + |
| 219 | +Forced Color Schemes: the 'forced-color-adjust' property {#forced} |
| 220 | +==================== |
| 221 | + |
| 222 | + <pre class=propdef> |
| 223 | + Name: forced-color-adjust |
| 224 | + Value: auto | none |
| 225 | + Initial: auto |
| 226 | + Applies to: all elements |
| 227 | + Inherited: yes |
| 228 | + </pre> |
| 229 | + |
| 230 | + |
| 231 | +Performance-based Color Schemes: the 'color-adjust' property {#perf} |
| 232 | +=============================== |
| 233 | + |
| 234 | + On most monitors, |
| 235 | + the color choices that authors make have no significant difference |
| 236 | + in terms of how the device performs; |
| 237 | + displaying a document with a white background or a black background is approximately equally easy. |
| 238 | + |
| 239 | + However, some devices have limitations and other qualities that make this assumption untrue. |
| 240 | + For example, |
| 241 | + printers tend to print on white paper; |
| 242 | + a document with a white background thus has to spend no ink on drawing that background, |
| 243 | + while a document with a black background will have to expend a large amount of ink filling in the background color. |
| 244 | + This tends to look fairly bad, |
| 245 | + and sometimes has deleterious physical effects on the paper, |
| 246 | + not to mention the vastly increased printing cost from expending the extra ink. |
| 247 | + Even fairly small differences, |
| 248 | + such as coloring text black versus dark gray, |
| 249 | + can be quite different when printing, |
| 250 | + as it switches from using a single black ink |
| 251 | + to a mixture of cyan, magenta, and yellow ink, |
| 252 | + resulting in higher ink usage and lower resolution. |
| 253 | + |
| 254 | + As a result, in some circumstances user agents will alter the styles an author specifies in some particular context, |
| 255 | + adjusting them to be more appropriate for the output device |
| 256 | + and to accommodate what they assume the user would prefer. |
| 257 | + However, in some cases the document may be using colors in important, well-thought-out ways that the user would appreciate, |
| 258 | + and so the document would like some way to hint to the user agent that it might want to respect the page's color choices. |
| 259 | + The 'color-adjust' property controls this. |
| 260 | + |
| 261 | + <pre class='propdef'> |
| 262 | + Name: color-adjust |
| 263 | + Value: economy | exact |
| 264 | + Initial: economy |
| 265 | + Applies to: all elements |
| 266 | + Percentages: N/A |
| 267 | + Inherited: yes |
| 268 | + Computed value: specified keyword |
| 269 | + Animation type: discrete |
| 270 | + </pre> |
| 271 | + |
| 272 | + The 'color-adjust' property provides a hint to the user-agent about how it should treat color and style choices |
| 273 | + that might be expensive or generally unwise on a given device, |
| 274 | + such as using light text on a dark background in a printed document. |
| 275 | + If user agents allow users to control this aspect of the document's display, |
| 276 | + the user preference <strong>must</strong> be respected more strongly |
| 277 | + than the hint provided by 'color-adjust'. |
| 278 | + It has the following values: |
| 279 | + |
| 280 | + <dl dfn-type=value dfn-for=color-adjust> |
| 281 | + <dt><dfn>economy</dfn> |
| 282 | + <dd> |
| 283 | + The user agent should make adjustments to the page's styling |
| 284 | + as it deems necessary and prudent for the output device. |
| 285 | + |
| 286 | + For example, if the document is being printed, |
| 287 | + a user agent might ignore any backgrounds |
| 288 | + and adjust text color to be sufficiently dark, |
| 289 | + to minimize ink usage. |
| 290 | + |
| 291 | + <dt><dfn>exact</dfn> |
| 292 | + <dd> |
| 293 | + This value indicates that the page is using color and styling on the specified element |
| 294 | + in a way which is important and significant, |
| 295 | + and which should not be tweaked or changed except at the user's request. |
| 296 | + |
| 297 | + For example, |
| 298 | + a mapping website offering printed directions |
| 299 | + might "zebra-stripe" the steps in the directions, |
| 300 | + alternating between white and light gray backgrounds. |
| 301 | + Losing this zebra-striping and having a pure-white background |
| 302 | + would make the directions harder to read with a quick glance |
| 303 | + when distracted in a car. |
| 304 | + </dl> |
0 commit comments