Create a Media Queries 5 specification

Reinstate the content that was taken out of Level 4, and
add 'prefers-reduced-motion'.

Author: grorg

mediaqueries-5/Overview.bs

@@ -0,0 +1,331 @@
+<pre class='metadata'>
+Title: Media Queries Level 5
+Group: csswg
+Shortname: mediaqueries
+Level: 5
+Status: ED
+Work Status: Exploring
+ED: https://drafts.csswg.org/mediaqueries-5/
+TR:
+Previous Version:
+Editor: Dean Jackson, Apple
+Editor: Florian Rivoal, Vivliostyle, http://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.
+Abstract:
+Abstract: Media Queries Level 5 describes the mechanism and syntax of media queries, media types, and media features. It extends and supersedes the features defined in Media Queries Level 4.
+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='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='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.
+
+	Note: For error handling purposes,
+	an undefined <a>media feature</a> is different from
+	a <a>media feature</a> that evaluates to false.
+	See <a href="#error-handling">Error Handling</a> 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>
+			&lt;script>
+			CSS.customMedia.set('--foo', 5);
+			&lt;/script>
+			&lt;style>
+			@media (_foo: 5) { ... }
+			@media (_foo < 10) { ... }
+			&lt;/style>
+		</pre>
+	</div>
+
+
+<!--
+  ██     ██  ██████  ████████ ████████  ████████  ████████  ████████ ████████  ██████
+  ██     ██ ██    ██ ██       ██     ██ ██     ██ ██     ██ ██       ██       ██    ██
+  ██     ██ ██       ██       ██     ██ ██     ██ ██     ██ ██       ██       ██
+  ██     ██  ██████  ██████   ████████  ████████  ████████  ██████   ██████    ██████
+  ██     ██       ██ ██       ██   ██   ██        ██   ██   ██       ██             ██
+  ██     ██ ██    ██ ██       ██    ██  ██        ██    ██  ██       ██       ██    ██
+   ███████   ██████  ████████ ██     ██ ██        ██     ██ ████████ ██        ██████
+-->
+
+<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.
+