Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation for forced colors mode #2819

Merged
merged 5 commits into from
Mar 16, 2021
Merged

Update documentation for forced colors mode #2819

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3796608
Update documentation for forced colors mode
dlibby- Mar 3, 2021
2ebe518
Address feedback
dlibby- Mar 5, 2021
192b942
Clarify system colors and modify wording
dlibby- Mar 5, 2021
f4d4001
Address more feedback
dlibby- Mar 9, 2021
c5e55af
Address another round of feedback
dlibby- Mar 16, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 39 additions & 22 deletions files/en-us/web/css/@media/forced-colors/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,7 @@
---
<div>{{CSSRef}}</div>

<p><span class="seoSummary">The <strong><code>forced-colors</code></strong> <a href="/en-US/docs/Web/CSS">CSS</a> <a href="/en-US/docs/Web/CSS/Media_Queries/Using_media_queries#Media_features">media feature</a> is used to detect if the {{Glossary("user agent")}} has enabled a forced colors mode where it enforces a user-chosen limited color palette on the page.</span></p>

<div class="notecard note">
<p><strong>Note:</strong> This feature is not supported by any user agent and its specifics are subject to change.</p>
</div>
<p><span class="seoSummary">The <strong><code>forced-colors</code></strong> <a href="/en-US/docs/Web/CSS">CSS</a> <a href="/en-US/docs/Web/CSS/Media_Queries/Using_media_queries#Media_features">media feature</a> is used to detect if the {{Glossary("user agent")}} has enabled a forced colors mode, such as Windows High Contrast, where it enforces a user-chosen limited color palette on the page.</span></p>
dlibby- marked this conversation as resolved.
Show resolved Hide resolved

<h2 id="Syntax">Syntax</h2>

Expand All @@ -26,60 +22,81 @@ <h3 id="Values">Values</h3>
<dt><code><dfn>none</dfn></code></dt>
<dd>Forced colors mode is not active; the page’s colors are not being forced into a limited palette.</dd>
<dt><code>active</code></dt>
<dd>Indicates that forced colors mode is active. The browser provides the color palette to authors through the <a href="/en-US/docs/Web/CSS/color_value#System_Colors">CSS system color</a> keywords and, if appropriate, it triggers the appropriate value of <code><a href="/en-US/docs/Web/CSS/@media/prefers-color-scheme">prefers-color-scheme</a></code> so that authors can adapt the page.</dd>
<dd>Indicates that forced colors mode is active. The browser provides the color palette to authors through the <a href="/en-US/docs/Web/CSS/color_value#System_Colors">CSS system color</a> keywords and, if appropriate, triggers the appropriate value of <code><a href="/en-US/docs/Web/CSS/@media/prefers-color-scheme">prefers-color-scheme</a></code> so that authors can adapt the page. The browser selects the value for <code>prefers-color-scheme</code> based on the lightness of the <code>Canvas</code> system color (see the <a href="https://www.w3.org/TR/css-color-adjust-1/#forced">color adjust spec</a> for more details).</dd>
</dl>

<h2 id="Usage_notes">Usage notes</h2>

<h3 id="Properties_affected_by_forced-color_mode">Properties affected by forced-color mode</h3>

<p>In forced colors mode, the values of the following properties are treated as if they have no author-level values specified. That is, user-specified values (if any) or browser-specified values are used instead.</p>
<p>In forced colors mode, the values of the following properties are treated as if they have no author-level values specified. That is, browser-specified values are used instead. The browser-specified values do not affect the style cascade; the values are instead forced by the browser at paint time. These browser-specified values are selected from the set of system colors &emdash; this ensures a consistent contrast for common UI elements for users that have forced colors enabled.</p>
dlibby- marked this conversation as resolved.
Show resolved Hide resolved

<ul>
<li>{{cssxref("color")}}</li>
<li>{{cssxref("background-color")}}</li>
dlibby- marked this conversation as resolved.
Show resolved Hide resolved
<li>{{cssxref("text-decoration-color")}}</li>
<li>{{cssxref("text-emphasis-color")}}</li>
<li>{{cssxref("border-color")}}</li>
<li>{{cssxref("outline-color")}}</li>
<li>{{cssxref("column-rule-color")}}</li>
<li>{{cssxref("scrollbar-color")}}</li>
<li>{{cssxref("-webkit-tap-highlight-color")}}</li>
<li>{{cssxref("box-shadow")}}</li>
<li>{{cssxref("text-shadow")}}</li>
<li><a href="/en-US/docs/Web/SVG/Attribute/fill">SVG fill attribute</a></li>
<li><a href="/en-US/docs/Web/SVG/Attribute/stroke">SVG stroke attribute</a></li>
</ul>

<p>You can use <a href="/en-US/docs/Web/CSS/color_value#System_Colors">system color keywords</a> with any property <em>other</em> than those listed above, to ensure that the rest of the page integrates with the restricted color palette available in forced colors mode.</p>
<p>Additionally the following properties have special behavior in forced colors mode:</p>
<ul>
<li>{{cssxref("box-shadow")}} is forced to 'none'</li>
<li>{{cssxref("text-shadow")}} is forced to 'none'</li>
<li>{{cssxref("background-image")}} is forced to 'none' for values that are not url-based</li>
<li>{{cssxref("color-scheme")}} is forced to 'light dark'</li>
<li>{{cssxref("scrollbar-color")}} is forced to 'auto'</li>
</ul>

<p>The system colors that are forced for the above properties depend on the context of the element. For example the {{cssxref("color")}} property on button element will be forced to ButtonText, whereas on normal text it will be forced to CanvasText. See the list of system colors for additional details of when each might be appropriate in various UI contexts.</p>
dlibby- marked this conversation as resolved.
Show resolved Hide resolved

<p><strong>Note:</strong> user agents choose system colors based on native element semantics, <em>not</em> on added ARIA roles. As an example, adding <code>role="button"</code> to a div will not cause an element's color to be forced to <code>ButtonText</code></p>
dlibby- marked this conversation as resolved.
Show resolved Hide resolved

<p>In addition to these adjustments, browsers will help ensure text legibility by drawing “backplates” behind text. This is particularly important for preserving contrast when text is placed on top of images.
</p>

<p>There are two cases where the user agent does not force the values for the above properties &emdash; when a {{cssxref("forced-color-adjust")}} value of 'none' is applied to an element, or when a system color is specified by the author.</p>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<p>There are two cases where the user agent does not force the values for the above properties &emdash; when a {{cssxref("forced-color-adjust")}} value of 'none' is applied to an element, or when a system color is specified by the author.</p>
<p>There are two cases where the user agent does not force the values for the above properties &emdash; when a {{cssxref("forced-color-adjust")}} value of <code>none</code> is applied to an element, or when a system color is specified by the author.</p>


<p>When forced-color-adjust is set to 'none' on an element, none of the forced color values will apply, and author styles will be applied as normal. Additionally, the backplate for text will be disabled.</p>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<p>When forced-color-adjust is set to 'none' on an element, none of the forced color values will apply, and author styles will be applied as normal. Additionally, the backplate for text will be disabled.</p>
<p>When forced-color-adjust is set to <code>none</code> on an element, none of the forced color values will apply, and author styles will be applied as normal. Additionally, the backplate for text will be disabled.</p>

dlibby- marked this conversation as resolved.
Show resolved Hide resolved

<p>When a system color is specified, it will be used instead of the value that would otherwise have been forced.</p>

<p>You can also use system colors with any property <em>other</em> than those listed above, to ensure that the rest of the page integrates with the restricted color palette available in forced colors mode.</p>

<h3 id="User_preferences">User preferences</h3>

<p>This media feature is active only if the user has enabled color scheme preferences in their operating system. For example High Contrast mode on Windows.</p>
<p>This media feature is active only if the user has enabled color scheme preferences in their operating system. One example of such a feature is High Contrast mode on Windows.</p>

<h2 id="Examples">Examples</h2>

<div class="notecard note">
<p><strong>Note:</strong> The below example will only work when using a browser that supports this media feature, and with a preference such as High Contrast mode enabled in your OS.</p>
</div>

<p>This example has an annoying color palette by default. This example does not take advantage of the colors provided by the user agent.</p>
<p>This example is a button that normally gets its contrast via {{cssxref("box-shadow")}}. Under forced colors mode, box-shadow is forced to none, so the example uses the forced-colors media feature to ensure there is a border of the appropriate color (ButtonText in this case)</p>

<h3 id="HTML">HTML</h3>

<pre class="brush: html">&lt;div class="colors"&gt;weird color box&lt;/div&gt;
<pre class="brush: html">&lt;button class="button"&gt;Press me!&lt;/button&gt;
</pre>

<h3 id="CSS">CSS</h3>

<pre class="brush: css">.colors {
background-color: red;
color: grey;
<pre class="brush: css">
.button {
border: 0;
padding: 10px;
box-shadow: -2px -2px 5px gray, 2px 2px 5px gray;
}

@media (forced-colors: active) {
.colors {
background-color: white;
color: black;
.button {
/* Use a border instead, since box-shadow is forced to 'none' in forced-colors mode */
border: 2px ButtonText solid;
}
}
</pre>
Expand Down Expand Up @@ -120,5 +137,5 @@ <h2 id="See_also">See also</h2>
<ul>
<li><a href="/en-US/docs/Web/CSS/@media">@media</a></li>
<li><a href="https://blogs.windows.com/msedgedev/2020/09/17/styling-for-windows-high-contrast-with-new-standards-for-forced-colors/">Styling for Windows high contrast with standards for forced colors.</a></li>
<li>{{cssxref("forced-color-adjust")}}</li>
<li>{{cssxref("forced-color-adjust")}}</li>
</ul>
12 changes: 6 additions & 6 deletions files/en-us/web/css/color_value/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -926,19 +926,19 @@ <h3 id="System_Colors">System Colors</h3>
</dd>
<dt>ButtonFace</dt>
<dd>
<p>Background of push buttons</p>
<p>Background color of controls</p>
</dd>
<dt>ButtonText</dt>
<dd>
<p>Text of push buttons</p>
<p>Foreground color of controls</p>
</dd>
<dt>Canvas</dt>
<dd>
<p>Background of application content or documents</p>
</dd>
<dt>CanvasText</dt>
<dd>
<p>Text in application content or documents</p>
<p>Foreground color in application content or documents</p>
</dd>
<dt>Field</dt>
<dd>
Expand All @@ -950,15 +950,15 @@ <h3 id="System_Colors">System Colors</h3>
</dd>
<dt>GrayText</dt>
<dd>
<p>Text that is disabled</p>
<p>Foreground color for disabled items (e.g. a disabled control)</p>
</dd>
<dt>Highlight</dt>
<dd>
<p>Background of items that are selected in a control</p>
<p>Background of selected items</p>
</dd>
<dt>HighlightText</dt>
<dd>
<p>Text of items that are selected in a control</p>
<p>Foreground color of selected items</p>
</dd>
<dt>LinkText</dt>
<dd>
Expand Down