Overview.bs

<pre class='metadata'>
Title: CSS High Contrast
Group: csswg
Shortname: high-contrast
Level: 1
Status: UD
Status Text: Once complete, this specification will include and extend <cite>Media Queries Level&nbsp;4.</cite> [[MEDIAQUERIES-4]]
Work Status: Exploring
ED:
TR:
Previous Version:
Editor: Rossen Atanassov, Microsoft, ratan@microsoft.com, w3cid 49885
Editor: Melanie Richards, Microsoft, mrichards@microsoft.com
Abstract: <a>High Contrast</a> allows authors to detect and participate in high contrast mode changes.
Ignored Terms: high contrast
</pre>

<pre class=link-defaults>
spec:css-values-3; type:value; text:in
</pre>

<h2 id="intro">
Introduction</h2>

	High contrast is an accessibility feature intended to increase the readability of text while 
	reducing cognitive load. The OS platform feature works by enabling the user to select theme colors 
	for a scoped number of semantic elements. This scheme can then be applied to user interfaces (UI) 
	and app content, reducing the visual complexity of the UI while guaranteeing the user's preferred 
	contrast level. Many people may find it more comfortable to read digital text consistently tailored 
	to their theme. To honor this strong user preference, this color mode is typically automatically 
	applied to web content.

<h2 id='nc-mediaquery'>
Media Query</h2>

	To allow developers to make style adjustments when high contrast styles are applied, a media query 
	type called 'high-contrast' would be added. If a high-contrast media query evaluates to true, any 
	styles defined within that media query will be used when in high contrast, and will not be overridden 
	by the high contrast feature.

<h3 id="high-contrast">
Detecting the high contrast color mode: the 'high-contrast' feature</h3>

	<pre class='descdef mq'>
	Name: high-contrast
	Value: active | black-on-white | white-on-black
	For: @media
	Type: discrete
	</pre>

	The 'high-contrast' media feature is used to query about the presence of the high contrast color 
	mode on the system, to allow the author to adjust style of the document in response. The following 
	values are valid:

	<dl dfn-type=value dfn-for="@media/high-contrast">
		<dt><dfn>active</dfn></dt>
		<dd>
			The device is used in a high contrast environment, where color mode is used to improve the 
			contrast between foregrounds and backrounds. Evaluates to true regardless of whether the 
			particular scheme is black-on-white, white-on-black, or other.
		</dd>
		<dt><dfn>black-on-white</dfn></dt>
		<dd>
			Evaluates to true when high contrast is enabled under the black-on-white color theme.
		</dd>
		<dt><dfn>white-on-black</dfn>
		<dd>
			Evaluates to true when high contrast is enabled under the white-on-black color theme.
		</dd>
	</dl>

	<div class="example">
		<pre class="lang-css">
			/**
		   * Author's icons are typically presented in a brand color; author wishes to match these
			 * to the contextual text color in any high contrast scheme.
		   */

			@media (high-contrast: active) {
				.icon path {
					stroke: currentColor;
				}
			}
		</pre>
	</div>

	<div class="example">
		<pre class="lang-css">
			/**
		   * Author wishes to add a subtle background effect in high contrast environments where 
			 * the general theme is known.
		   */

			@media (high-contrast: black-on-white) {
				header {
					background: linear-gradient(#dedede, #fff 2em);
				}
			}

			@media (high-contrast: white-on-black) {
				header {
					background: linear-gradient(#333, #000 2em);
				}
			}
		</pre>
	</div>

  Issue: The naming of 'high-contrast' comes from the Windows theming feature, and a more general 
	name can be considered (e.g. <code>user-color-mode</code>) to provide for future color modes. In such a case, 
	a general 'high-contrast' value keyword may be added to distinguish from activation of 
	<strong>any</strong> color mode.

<h2 id='hc-adjust'>
High Contrast Adjust</h2>

	In some cases, it may be appropriate to override high contrast styles applied by the user agent: for 
	example if the color is important to consuming the content, or the author wishes to apply high contrast 
	colors in a manner different to the user agent stylesheet. A 'high-contrast-adjust' property would 
	enable the author to prevent the high contrast mode from adjusting styles.

<h3 id="high-contrast-adjust">
Overriding the high contrast color mode: the 'high-contrast-adjust' property</h3>

	<pre class='propdef'>
	Name: high-contrast-adjust
	Value: auto | none
	Initial: auto
	Applies to: all elements
	Inherited: no
	Computed value: specified keyword
	Animation type: not animatable
	</pre>

  <dl dfn-for="high-contrast-override" dfn-type=value>
		<dt><dfn>auto</dfn></dt>
		<dd>
			Indicates the applicable CSS properties will be adjusted as expected when the system is in high 
			contrast mode.
		</dd>
		<dt><dfn>none</dfn>
		<dd>
			Indicates the applicable CSS properties will not be adjusted when the system is in high contrast 
			mode. Applies to the given element and its subtree.
		</dd>
	</dl>

	<div class="example">
		<pre class="lang-css">
			/**
			* Author preserves brand colors in a style guide
			*/
			@media (high-contrast: active) {
				.color-swatch {
					high-contrast-adjust: none;
				}
			}
		</pre>
	</div>

	<div class="example">
		<pre class="lang-css">
			/**
			* Author wishes to style popular highlights in an article, which may contain links
			*/
			@media (high-contrast: active) {
				.highlight {
					high-contrast-adjust: none;
					color: Window;
					background: WindowText;
				}

				.highlight a:link,
				.highlight a:visited {
					border-bottom: 2px solid;
					color: Window;
				}
			}
		</pre>
	</div>

	Note: The example uses CSS System Colors to set content to abstracted user colors. This could be 
	alternatively achieved by extending the available environment variables accessed via <code>env()</code>.

<h2 id='hc-cascade'>
Cascade Order</h2>

	High contrast color schemes work by overriding user defined styles for various 
	CSS properties in order to ensure readability. The process model for such high contrast overrides is 
	as follows:

	Given an element and a declaration from a CSS rule whose selector matches that element, the application 
	of that declaration will be suppressed if all of the following conditions are met:

	1. The declaration is for a CSS property in the set of properties that are adjusted for high contrast 
	(as defined by the user agent style sheet)
	2. High contrast mode is enabled in the host environment
	3. The computed value of 'high-contrast-adjust' on the element or its ancestor is <code>auto</code>
	4. The rule is not contained (directly or indirectly) inside an <code>@media</code> block matching the 'high-contrast' media feature
	5. The rule is not defined in the default user agent style sheet

	If all of the above conditions are met, the computed color value of the CSS property is overridden by 
	a system color value.

<h2 class="no-num" id="acknowledgments">
Acknowledgments</h2>

	This specification is the product of the W3C Working Group on Cascading Style Sheets.