-
Notifications
You must be signed in to change notification settings - Fork 790
Expand file tree
/
Copy pathOverview.bs
More file actions
508 lines (418 loc) · 20.1 KB
/
Overview.bs
File metadata and controls
508 lines (418 loc) · 20.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
<pre class='metadata'>
Title: Media Queries Level 5
Group: csswg
Shortname: mediaqueries-5
Level: 5
Status: ED
Status Text: Once complete, this specification will include and extend <cite>Media Queries Level 4.</cite> [[MEDIAQUERIES-4]]
Work Status: Exploring
ED: https://drafts.csswg.org/mediaqueries-5/
TR:
Previous Version:
Editor: Dean Jackson, Apple
Editor: Florian Rivoal, Vivliostyle, https://florian.rivoal.net, http://vivliostyle.com, w3cid 43241
Editor: Tab Atkins Jr., Google, http://xanthir.com/contact/, w3cid 42199
Abstract: <a>Media Queries</a> allow authors to test and query values or features of the user agent or display device, independent of the document being rendered. They are used in the CSS @media rule to conditionally apply styles to a document, and in various other contexts and languages, such as HTML and Javascript.
Ignored Terms: min-resolution, max-resolution, none, view-mode, mediaText, DOMString
Link Defaults: css-break-3 (property) break-inside
Link Defaults: css-cascade-3 (at-rule) @import
</pre>
<pre class=link-defaults>
spec:css-values-3; type:value; text:in
</pre>
<h2 id="intro">
Introduction</h2>
Note: At the time of writing, [[MEDIAQUERIES-4]] is not completely finalized yet.
To avoid accidental divergences and maintenance overhead,
This specification is written as a delta specification over Media Queries Level 4.
Once the level 4 specification is final,
its content will be integrated into this specification,
which will then replace it.
Until then, Media Queries Level 5 only contains additions and extensions to level 4.
<h3 id='mq-features'>
Media Features</h3>
Issue: Copy level 4 prose when final
<h4 id='mq-boolean-context'>
Evaluating Media Features in a Boolean Context</h4>
Issue: Copy level 4 prose when final, except the following paragraph which is changed compared to level 4.
When written like this, the <a>media feature</a> is evaluated in a <dfn export>boolean context</dfn>.
If the feature would be true for any value
<em>other than</em> the number ''0'',
a <<dimension>> with the value ''0'',
the keyword ''@media/update/none'',
or a value explicitely defined by that media feature to evaluate as false in a boolean context,
the <a>media feature</a> evaluates to true.
Otherwise, it evaluates to false.
<!--
████████ ██ ██ ██ ██
██ ███ ██ ██ ██
██ ████ ██ ██ ██
██████ ██ ██ ██ ██ ██
██ ██ ████ ██ ██
██ ██ ███ ██ ██
████████ ██ ██ ███
-->
<h2 id='mf-environment'>
Environment Media Features</h2>
<h3 id="light-level">
Detecting the ambient light level: the 'light-level' feature</h3>
<pre class='descdef mq'>
Name: light-level
Value: dim | normal | washed
For: @media
Type: discrete
</pre>
The 'light-level' media feature is used to query about the ambient light-level in which the device is used,
to allow the author to adjust style of the document in response.
The following values are valid:
<dl dfn-type=value dfn-for="@media/light-level">
<dt><dfn>dim</dfn>
<dd>
The device is used in a dim environment,
where excessive contrast and brightness would be distracting or uncomfortable to the reader.
For example: night time, or a dimly illuminated indoor environment.
<dt><dfn>normal</dfn>
<dd>
The device is used in a environment with a light level in the ideal range for the screen,
and which does not necessitate any particular adjustment.
<dt><dfn>washed</dfn>
<dd>
The device is used in an exceptionally bright environment,
causing the screen to be washed out and difficult to read.
For example: bright daylight.
</dl>
User agents should set the thresholds between the three levels
in a way that takes into account the characteristics of the device.
<div class="note">
Even though it is expected that User Agents will adjust the value of this media feature
based on ambient light sensors,
this specification intentionally refrains from defining the three levels in terms of a measurement in lux,
for several reasons:
<ul>
<li>
Devices equipped with a light sensor usually adjust the brightness of the screen automatically.
Depending on the level of adjustment,
the thresholds for needing a low contrast or hight contrast content may vary.
<li>
Different screen technologies wash out at very different ambient light levels;
e-ink displays remain readable in bright daylight,
while liquid crystal displays do not.
<li>
Many embedded light sensors are inaccurately calibrated,
making it difficult to establish useful thresholds valid across devices.
</ul>
</div>
For accessibility purposes, user agents may offer manual controls
allowing the user to switch between the three levels of independently of the ambient light level,
as high contrast or low contrast styles may be more suitable for users with visual disabilities.
<p class="issue">
Using this media feature for accessibility purposes overlaps a lot with <a href="http://msdn.microsoft.com/en-us/library/windows/apps/hh465764.aspx">the high-contrast media feature proposed by Microsoft</a>.
Can we adjust this so that it covers all use cases for both,
or somehow modify them to work in an orthogonal, rather than overlapping, fashion?
<div class="example">
<pre>
@media (light-level: normal) {
p { background: url("texture.jpg"); color: #333 }
}
@media (light-level: dim) {
p { background: #222; color: #ccc }
}
@media (light-level: washed) {
p { background: white; color: black; font-size: 2em; }
}
</pre>
</div>
<!--
██████ ██████ ████████ ████ ████████ ████████ ████ ██ ██ ██████
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ██ ██
██████ ██ ████████ ██ ████████ ██ ██ ██ ██ ██ ██ ████
██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ██ ██
██████ ██████ ██ ██ ████ ██ ██ ████ ██ ██ ██████
-->
<h2 id='mf-scripting'>
Scripting Media Features</h2>
<h3 id="scripting">
Scripting Support: the 'scripting' feature</h3>
<pre class='descdef mq'>
Name: scripting
Value: none | initial-only | enabled
For: @media
Type: discrete
</pre>
The 'scripting' media feature is used to query whether scripting languages,
such as JavaScript,
are supported on the current document.
<dl dfn-type=value dfn-for="@media/scripting">
<dt><dfn>enabled</dfn>
<dd>
Indicates that the user agent supports scripting of the page,
and that scripting in the current document is enabled
for the lifetime of the document.
<dt><dfn>initial-only</dfn>
<dd>
Indicates that the user agent supports scripting of the page,
and that scripting in the current document is enabled during the initial page load,
but is not supported afterwards.
Examples are printed pages,
or pre-rendering network proxies
that render a page on a server
and send a nearly-static version of the page to the user.
Issue(503): Should there be an explicit minimum threshold to meet
before a UA is allowed to claim ''initial-only''?
Having one would mean authors would know
what they can depend on,
and could tailor their scripts accordingly.
On the other hand, pinpointing that threshold is difficult:
if it is set too low,
the scripting facilities that authors can depend on
may be to constrained to be practical,
even though actual UAs may potentially
all support significantly more.
But trying to set it higher may cause us to exclude
UAs that do support scripting at loading time,
but restrict it in some cases based on complex heuristics.
For instance, conservative definitions likely include at least
running all inline scripts and firing the DOMContentLoaded event.
But it does not seem useful for authors to constrain themselves to this
if most (or maybe all) ''initial-only'' UAs
also load external scripts (including ''async'' and ''defer'')
and fire the load event.
On the other hand,
requiring external scripts to be loaded
and the load event to be fired
could exclude UAs like Opera mini,
which typically do run them,
but may decide not to based on timeouts and other heuristics.
<dt><dfn>none</dfn>
<dd>
Indicates that the user agent will not run scripts for this document;
either it doesn't support a scripting language,
or the support isn't active for the current document.
</dl>
Some user agents have the ability to turn off scripting support on a per script basis or per domain basis,
allowing some, but not all, scripts to run in a particular document.
The 'scripting' media feature does not allow fine grained detection of which script is allowed to run.
In this scenario, the value of the 'scripting' media feature should be ''scripting/enabled'' or ''scripting/initial-only''
if scripts originating on the same domain as the document are allowed to run,
and ''scripting/none'' otherwise.
Note: A future level of CSS may extend this media feature to allow fine-grained detection of which script is allowed to run.
<!--
██████ ██ ██ ██████ ████████ ███████ ██ ██ ██ ██ ███████
██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ███ ███ ███ ██ ██
██ ██ ██ ██ ██ ██ ██ ████ ████ ████ ████ ██ ██
██ ██ ██ ██████ ██ ██ ██ ██ ███ ██ ██ ███ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██████ ███████ ██████ ██ ███████ ██ ██ ██ ██ █████ ██
-->
<h2 id='custom-mq'>
Custom Media Queries</h2>
When designing documents that use media queries,
the same media query may be used in multiple places,
such as to qualify multiple ''@import'' statements.
Repeating the same media query multiple times is an editing hazard;
an author making a change must edit every copy in the same way,
or suffer from difficult-to-find bugs in their CSS.
To help ameliorate this,
this specification defines a method of defining <a>custom media queries</a>,
which are simply-named aliases for longer and more complex media queries.
In this way, a media query used in multiple places can instead be assigned to a <a>custom media query</a>,
which can be used everywhere,
and editing the media query requires touching only one line of code.
A <dfn>custom media query</dfn> is defined with the ''@custom-media'' rule:
<pre class='prod'>
<dfn>@custom-media</dfn> = @custom-media <<extension-name>> [ <<media-query-list>> | true | false ] ;
</pre>
The <<extension-name>> can then be used in a <a>media feature</a>.
It <strong>must</strong> be used in a <a>boolean context</a>;
using them in a normal or <a>range context</a> is a syntax error.
If a <<media-query-list>> is given,
the <a>custom media query</a> evaluates to true
if the <<media-query-list>> it represents evaluates to true,
and false otherwise.
If <dfn value for="@custom-media">true</dfn> or <dfn value for="@custom-media">false</dfn> is given,
the <a>custom media query</a> evaluates to true or false, respectively.
A ''@custom-media'' rule can refer to other <a>custom media queries</a>.
However, loops are forbidden,
and a <a>custom media query</a> must not be defined in terms of itself or
of another <a>custom media query</a> that directly or indirectly refers to it.
Any such attempt of defining a <a>custom media query</a> with a circular dependency
must cause all the <a>custom media queries</a> in the loop to fail to be defined.
If multiple ''@custom-media'' rules declare the same <<extension-name>>,
the truth value is based on the last one alone,
ignoring all previous declarations of the same <<extension-name>>.
Note: For error handling purposes,
an undefined <a>media feature</a> is different from
a <a>media feature</a> that evaluates to false.
See [[mediaqueries-4#error-handling]] for details.
<div class='example'>
For example, if a responsive site uses a particular breakpoint in several places,
it can alias that with a reasonable name:
<pre>
@custom-media --narrow-window (max-width: 30em);
@media (--narrow-window) {
/* narrow window styles */
}
@media (--narrow-window) and (script) {
/* special styles for when script is allowed */
}
/* etc */
</pre>
</div>
<h3 id='script-custom-mq'>
Script-based Custom Media Queries</h3>
<div class='issue'>
Define a map of names to values for JS.
Values can be either a MediaQueryList object or a boolean,
in which case it's treated identically to the above,
or can be a number or a string,
in which case it's treated like a normal MQ,
and can use the normal or range context syntax.
Like:
<pre>
<script>
CSS.customMedia.set('--foo', 5);
</script>
<style>
@media (_foo: 5) { ... }
@media (_foo < 10) { ... }
</style>
</pre>
</div>
<!--
██████ ██████ ██████ ███████ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ███ ███
██ ██ ██ ██ ██ ████ ████
██ ██████ ██████ ██ ██ ██ ███ ██
██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██████ ██████ ██████ ███████ ██ ██
-->
<!--
<h2 id='custom-mq-cssom'>
CSSOM</h2>
The <a interface>CSSRule</a> interface is extended as follows:
<pre class="idl partial">
partial interface CSSRule {
const unsigned short CUSTOM_MEDIA_RULE = 17;
};
</pre>
The <a interface>CSSCustomMediaRule</a> interface represents a ''@custom-media'' rule.
<pre class="idl">
interface CSSCustomMediaRule : CSSRule {
attribute CSSOMString name;
[SameObject, PutForwards=mediaText] readonly attribute MediaList media;
};
</pre>
<dl dfn-type=attribute dfn-for=CSSCustomMediaRule>
<dt><dfn>name</dfn>, of type <code>CSSOMString</code>
<dd>
The <a attribute>name</a> attribute on getting must return a <code>CSSOMString</code> object
that contains the serialization of the <<extension-name>> defined for the associated rule.
On setting the <a attribute>name</a> attribute,
run the following steps:
<ol>
<li><a>Parse a component value</a> from the value.
<li>
If the returned value is an <<extension-name>>,
replace the associated rule's name with the <<extension-name>>'s representation.
<li>
Otherwise, do nothing.
</ol>
<dt><dfn>media</dfn>, of type <a interface>MediaList</a>, readonly
<dd>
The <a attribute>media</a> attribute must return a <a interface>MediaList</a> object
for the <<media-query-list>> specified with the associated rule.
</dl>
-->
<!--
██ ██ ██████ ████████ ████████ ████████ ████████ ████████ ████████ ██████
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██████ ██████ ████████ ████████ ████████ ██████ ██████ ██████
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
███████ ██████ ████████ ██ ██ ██ ██ ██ ████████ ██ ██████
-->
<h2 id='mf-user-preferences'>
User Preference Media Features</h2>
<h3 id="inverted">
Detecting the desire for inverted colors on the display: the 'inverted-colors' feature</h3>
<pre class='descdef mq'>
Name: inverted-colors
Value: none | inverted
For: @media
Type: discrete
</pre>
The 'inverted-colors' media feature indicates whether the content is displayed normally, or whether colors have been inverted.
Note: This is an indication that the user agent or underlying
operating system has forcibly inverted all colors, not a request to do so. This
is sometimes provided as a simple accessibility feature, allowing users to
switch between light-on-dark and dark-on-light text. However, this has
unpleasant side effects, such as inverting pictures, or turning shadows into
highlights, which reduce the readability of the content.
<dl dfn-type=value dfn-for="@media/inverted-colors">
<dt><dfn>none</dfn>
<dd>
Colors are displayed normally.
<dt><dfn>inverted</dfn>
<dd>
All pixels within the displayed area have been inverted.
</dl>
<div class="example">
For example, a user frequently using their operating system's ability to invert the screens color
may want to add the following to their user style sheet,
to limit the undesirable side effects of the inversion.
<pre>
@media (inverted-colors) {
img { filter: invert(100%); }
* { text-shadow: none; box-shadow: none; }
}
</pre>
</div>
<h3 id="prefers-reduced-motion">
Detecting the desire for less motion on the page: the 'prefers-reduced-motion' feature</h3>
<pre class='descdef mq'>
Name: prefers-reduced-motion
Value: no-preference | reduce
For: @media
Type: discrete
</pre>
The 'prefers-reduced-motion' media feature is used to detect if the user
has requested the system minimize the amount of animation or motion it
uses.
<dl dfn-type=value dfn-for="@media/prefers-reduced-motion">
<dt><dfn>no-preference</dfn>
<dd>
Indicates that the user has made no preference known
to the system. This keyword value evaluates as false
in the <a>boolean context</a>.
<dt><dfn>reduce</dfn>
<dd>
Indicates that user has notified the system that they
prefer an interface that minimizes the amount of movement
or animation, preferably to the point where all non-essential
movement is removed.
</dl>
<h2 id="changes" class="no-num">
Changes</h2>
<h3 id="changes-2017">
Changes Since the Media Queries Level 4</h3>
The following changes were made to this specification since the
<a href="https://www.w3.org/TR/mediaqueries-4/">6 July 20126 Working Draft of Media Queries Level 4</a>:
<ul>
<li>
Reinstate 'light-level', 'inverted-colors' and Custom Media Queries sections from the
Media Queries Level 4 drafts.
<li>
Add 'prefers-reduced-motion' media feature.
</ul>
<h2 class="no-num" id="acknowledgments">
Acknowledgments</h2>
This specification is the product of the W3C Working Group on
Cascading Style Sheets.
Comments from
James Craig
improved this specification.