Document Sec-CH-Prefers-Color-Scheme Client Hint header (mdn#22266)

* Document two Sec-CH-* Client Hint headers

* f

* Sec-CH-Save-Data

* Standard template

* Add Sec-CH-Save-Data to network client hints

* f

* Apply suggestions from code review

* Apply suggestions from code review

* Update files/en-us/web/http/headers/sec-ch-save-data/index.md

* Apply suggestions from code review

* Apply suggestions from code review

* f

* f

* f

* f

* f

* Chris typo fixes

* Add link in accessibility section

* Update files/en-us/web/http/headers/sec-ch-prefers-color-scheme/index.md

* Update files/en-us/web/css/@media/index.md

Co-authored-by: Hamish Willee <[email protected]>

* Update files/en-us/web/css/transition-timing-function/index.md

Co-authored-by: Hamish Willee <[email protected]>

* Update files/en-us/web/html/element/portal/index.md

Co-authored-by: Hamish Willee <[email protected]>

* Update files/en-us/web/http/headers/sec-ch-prefers-color-scheme/index.md

Co-authored-by: Hamish Willee <[email protected]>

* Update files/en-us/web/http/headers/sec-ch-prefers-color-scheme/index.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Update files/en-us/web/http/headers/sec-ch-prefers-color-scheme/index.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Move user agent client hints section

As suggested by Hamish

* Update files/en-us/web/http/headers/sec-ch-prefers-color-scheme/index.md

Co-authored-by: Hamish Willee <[email protected]>

* Reduce repetition of text following table

* fix(API): Missing newline at EOF

* Remove duplicate Sec-CH-Prefers-Reduced-Motion

This removes the original, because I like these two items together at the end, and the new description is better.

* Update files/en-us/web/api/animation/index.md

Co-authored-by: Hamish Willee <[email protected]>

* Update files/en-us/web/css/@media/index.md

Co-authored-by: Hamish Willee <[email protected]>

* Update files/en-us/web/css/@media/index.md

Co-authored-by: Hamish Willee <[email protected]>

* Update listed ua client hints

---------

Co-authored-by: Hamish Willee <[email protected]>
Co-authored-by: Chris Mills <[email protected]>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Brian Thomas Smith <[email protected]>

files/en-us/web/api/animation/index.md

@@ -73,7 +73,7 @@ The **`Animation`** interface of the [Web Animations API](/en-US/docs/Web/API/We
 
 Blinking and flashing animation can be problematic for people with cognitive concerns such as Attention Deficit Hyperactivity Disorder (ADHD). Additionally, certain kinds of motion can be a trigger for Vestibular disorders, epilepsy, and migraine, and Scotopic sensitivity.
 
-Consider providing a mechanism for pausing or disabling animation, as well as using the [Reduced Motion Media Query](/en-US/docs/Web/CSS/@media/prefers-reduced-motion) to create a complimentary experience for users who have expressed a preference for no animated experiences.
+Consider providing a mechanism for pausing or disabling animation, as well as using the [Reduced Motion Media Query](/en-US/docs/Web/CSS/@media/prefers-reduced-motion) (or equivalent [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) {{HTTPHeader("Sec-CH-Prefers-Reduced-Motion")}}) to create a complimentary experience for users who have expressed a preference for no animated experiences.
 
 - [Designing Safer Web Animation For Motion Sensitivity · An A List Apart Article](https://alistapart.com/article/designing-safer-web-animation-for-motion-sensitivity/)
 - [An Introduction to the Reduced Motion Media Query | CSS-Tricks](https://css-tricks.com/introduction-reduced-motion-media-query/)

files/en-us/web/css/@media/index.md

@@ -163,13 +163,20 @@ You can also combine multiple media queries into a single rule by separating the
 - `or`
   - : Equivalent to the `,` operator. Added in Media Queries Level 4.
 
+### User agent client hints
+
+Some media queries have corresponding [user agent client hints](/en-US/docs/Web/HTTP/Client_hints).
+These are HTTP headers that request content that is pre-optimized for the particular media requirement.
+They include {{HTTPHeader("Sec-CH-Prefers-Color-Scheme")}} and {{HTTPHeader("Sec-CH-Prefers-Reduced-Motion")}}.
+
 ## Accessibility concerns
 
 To best accommodate people who adjust a site's text size, use [`em`](/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#numeric_values)s when you need a {{cssxref("<length>")}} for your [media queries](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries).
 
 Both [`em`](/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#numeric_values) and [`px`](/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#numeric_values) are valid units, but [`em`](/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#numeric_values) works better if the user changes the browser text size.
 
-Also consider using Level 4 media queries to improve the user's experience. For example, `prefers-reduced-motion` to [detect if the user has requested that the system minimize the amount of animation](/en-US/docs/Web/CSS/@media/prefers-reduced-motion) or motion it uses.
+Also consider media queries or [HTTP user agent client hints](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) to improve the user's experience.
+For example, the media query [`prefers-reduced-motion`](/en-US/docs/Web/CSS/@media/prefers-reduced-motion) or the eqivalent HTTP header {{HTTPHeader("Sec-CH-Prefers-Reduced-Motion")}}) can be used to minimize the amount of animation or motion used based on user preferences.
 
 ## Security
 

files/en-us/web/css/@media/prefers-color-scheme/index.md

@@ -154,6 +154,7 @@ In this case, the parent element with a `color-scheme` CSS property is a `<div>`
 ## See also
 
 - {{cssxref("color-scheme")}} CSS property
+- {{HTTPHeader("Sec-CH-Prefers-Color-Scheme")}} HTTP Header [User Agent Client Hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints)
 - [Simulate prefers-color-scheme in Firefox](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/examine_and_edit_css/index.html#view-media-rules-for-prefers-color-scheme) (Firefox Page Inspector > Examine and edit CSS)
 - [Video tutorial: Coding a Dark Mode for your Website](https://www.youtube.com/watch?v=jmepqJ5UbuM)
 - [Redesigning your product and website for dark mode](https://stuffandnonsense.co.uk/blog/redesigning-your-product-and-website-for-dark-mode)

files/en-us/web/css/@media/prefers-reduced-motion/index.md

@@ -130,5 +130,6 @@ You can enable the setting for reducing motion on [your device](#user_preference
 
 ## See also
 
+- {{HTTPHeader("Sec-CH-Prefers-Reduced-Motion")}} HTTP Header [User Agent Client Hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints)
 - [An introduction to the reduced motion media query](https://css-tricks.com/introduction-reduced-motion-media-query/) on CSS-Tricks (2019)
 - [Responsive design for motion](https://webkit.org/blog/7551/responsive-design-for-motion/) on WebKit Blog (2017)

files/en-us/web/css/transition-timing-function/index.md

@@ -98,7 +98,7 @@ transition-timing-function: unset;
 
 Some animations can be helpful such as to guide users to understand what actions are expected, to show relationships within the user interface, and to inform users as to what actions have occurred. Animations can help reduce cognitive load, prevent change blindness, and establish better recall in spatial relationships. However, some animations can be problematic for people with cognitive concerns such as Attention Deficit Hyperactivity Disorder (ADHD) and certain kinds of motion can be a trigger for Vestibular disorders, epilepsy, and migraine and Scotopic sensitivity.
 
-Consider providing a mechanism for pausing or disabling animation, as well as using the [Reduced Motion Media Query](/en-US/docs/Web/CSS/@media/prefers-reduced-motion) to create a complimentary experience for users who have expressed a preference for no animated experiences.
+Consider providing a mechanism for pausing or disabling animation, as well as using the [Reduced Motion Media Query](/en-US/docs/Web/CSS/@media/prefers-reduced-motion) (or equivalent [User Agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) {{HTTPHeader("Sec-CH-Prefers-Reduced-Motion")}}) to create a complimentary experience for users who have expressed a preference for less animation.
 
 ## Formal definition
 

files/en-us/web/http/headers/index.md

@@ -80,8 +80,6 @@ The different categories of client hints are listed below.
 
 The [UA client hints](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) are request headers that provide information about the user agent, the platform/architecture it is running on, and user preferences set on the user agent or platform:
 
-- {{HTTPHeader("Sec-CH-Prefers-Reduced-Motion")}} {{experimental_inline}}
-  - : User agent's reduced motion preference setting.
 - {{HTTPHeader("Sec-CH-UA")}} {{experimental_inline}}
   - : User agent's branding and version.
 - {{HTTPHeader("Sec-CH-UA-Arch")}} {{experimental_inline}}
@@ -100,18 +98,22 @@ The [UA client hints](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints)
   - : User agent's underlying operation system/platform.
 - {{HTTPHeader("Sec-CH-UA-Platform-Version")}} {{experimental_inline}}
   - : User agent's underlying operation system version.
+- {{HTTPHeader("Sec-CH-UA-Prefers-Color-Scheme")}} {{experimental_inline}}
+  - : User's preference of dark or light color scheme.
+- {{HTTPHeader("Sec-CH-UA-Prefers-Reduced-Motion")}} {{experimental_inline}}
+  - : User's preference to see fewer animations and content layout shifts.
 
 ### Device client hints
 
-- {{HTTPHeader("Content-DPR")}} {{deprecated_inline}} {{experimental_inline}}
+- {{HTTPHeader("Content-DPR")}} {{deprecated_inline}}
   - : _Response header_ used to confirm the image device to pixel ratio in requests where the {{HTTPHeader("DPR")}} client hint was used to select an image resource.
-- {{HTTPHeader("Device-Memory")}} {{deprecated_inline}} {{experimental_inline}}
+- {{HTTPHeader("Device-Memory")}} {{deprecated_inline}}
   - : Approximate amount of available client RAM memory. This is part of the [Device Memory API](/en-US/docs/Web/API/Device_Memory_API).
-- {{HTTPHeader("DPR")}} {{deprecated_inline}} {{experimental_inline}}
+- {{HTTPHeader("DPR")}} {{deprecated_inline}}
   - : Client device pixel ratio (DPR), which is the number of physical device pixels corresponding to every CSS pixel.
-- {{HTTPHeader("Viewport-Width")}} {{deprecated_inline}} {{experimental_inline}}
+- {{HTTPHeader("Viewport-Width")}} {{deprecated_inline}}
   - : A number that indicates the layout viewport width in CSS pixels. The provided pixel value is a number rounded to the smallest following integer (i.e. ceiling value).
-- {{HTTPHeader("Width")}} {{deprecated_inline}} {{experimental_inline}}
+- {{HTTPHeader("Width")}} {{deprecated_inline}}
   - : A number that indicates the desired resource width in physical pixels (i.e. intrinsic size of an image).
 
 ### Network client hints
@@ -125,7 +127,7 @@ Network client hints allow a server to choose what information is sent based on
 - {{HTTPHeader("RTT")}}
   - : Application layer round trip time (RTT) in milliseconds, which includes the server processing time. This is part of the [Network Information API](/en-US/docs/Web/API/Network_Information_API).
 - {{HTTPHeader("Save-Data")}} {{experimental_inline}}
-  - : A boolean that indicates the user agent's preference for reduced data usage.
+  - : A string `on` that indicates the user agent's preference for reduced data usage.
 
 ## Conditionals
 

files/en-us/web/http/headers/save-data/index.md

@@ -67,15 +67,15 @@ instance ensuring that the user is not served a lower-quality image from the cac
 Request:
 
 ```http
-GET /image.jpg HTTP/1.0
+GET /image.jpg HTTP/1.1
 Host: example.com
 Save-Data: on
 ```
 
 Response:
 
 ```http
-HTTP/1.0 200 OK
+HTTP/1.1 200 OK
 Content-Length: 102832
 Vary: Accept-Encoding, Save-Data
 Cache-Control: public, max-age=31536000
@@ -89,14 +89,14 @@ Content-Type: image/jpeg
 Request:
 
 ```http
-GET /image.jpg HTTP/1.0
+GET /image.jpg HTTP/1.1
 Host: example.com
 ```
 
 Response:
 
 ```http
-HTTP/1.0 200 OK
+HTTP/1.1 200 OK
 Content-Length: 481770
 Vary: Accept-Encoding, Save-Data
 Cache-Control: public, max-age=31536000

files/en-us/web/http/headers/sec-ch-prefers-color-scheme/index.md

@@ -0,0 +1,99 @@
+---
+title: Sec-CH-Prefers-Color-Scheme
+slug: Web/HTTP/Headers/Sec-CH-Prefers-Color-Scheme
+browser-compat: http.headers.Sec-CH-Prefers-Color-Scheme
+---
+
+{{HTTPSidebar}}{{SeeCompatTable}}{{SecureContext_Header}}
+
+The **`Sec-CH-Prefers-Color-Scheme`** [user preference media feature client hint](/en-US/docs/Web/HTTP/Client_hints#user_preference_media_features_client_hints) request header provides the user's preference for light or dark color themes. A user indicates their preference through an operating system setting (for example, light or dark mode) or a user agent setting.
+
+If a server signals to a client via the {{httpheader("Accept-CH")}} header that it accepts `Sec-CH-Prefers-Color-Scheme`, the client can then respond with this header to indicate the user's preference for a specific color scheme. The server can send the client appropriately adapted content including images or CSS to display a light or dark mode for subsequent rendered content.
+
+This header is modeled on the {{cssxref("@media/prefers-color-scheme", "prefers-color-scheme")}} media query.
+
+<table class="properties">
+  <tbody>
+    <tr>
+      <th scope="row">Header type</th>
+      <td>
+        {{Glossary("Request header")}},
+        <a href="/en-US/docs/Web/HTTP/Client_hints">Client hint</a>
+      </td>
+    </tr>
+    <tr>
+      <th scope="row">{{Glossary("Forbidden header name")}}</th>
+      <td>yes</td>
+    </tr>
+  </tbody>
+</table>
+
+## Usage notes
+
+The **`Sec-CH-Prefers-Color-Scheme`** header allows sites to obtain user color scheme preference at request time; they could then choose to provide the relevant CSS for the user's preference inline, for performance reasons. If the server inlines the CSS, it might want to include a {{HTTPHeader("Vary")}} response header specifying `Sec-CH-Prefers-Color-Scheme`, to indicate that the response is tailored for a particular color scheme.
+
+If performance is not a critical consideration in this context, you could instead handle the user's color scheme preference using the [`prefers-color-scheme`](/en-US/docs/Web/CSS/@media/prefers-color-scheme) media query, and/or the {{domxref("Window.matchMedia()")}} API.
+
+`Sec-CH-Prefers-Color-Scheme` is a high entropy hint so the site needs to opt into receiving it by sending an appropriate {{HTTPHeader("Accept-CH")}} response header. A user agent may intentionally omit the `Sec-CH-Prefers-Color-Scheme` header to preserve user privacy since the user's preference could, in theory, be used for fingerprinting.
+
+## Syntax
+
+```http
+Sec-CH-Prefers-Color-Scheme: <preference>
+```
+
+### Directives
+
+- `<preference>`
+
+  - : A string indicating the user agent's preference for dark or light content: `"light"` or `"dark"`.
+    The value may originate from a corresponding setting in the underlying operating system.
+
+## Examples
+
+The client makes an initial request to the server:
+
+```http
+GET / HTTP/1.1
+Host: example.com
+```
+
+The server responds, telling the client via {{httpheader("Accept-CH")}} that it accepts `Sec-CH-Prefers-Color-Scheme`. In this example {{httpheader("Critical-CH")}} is also used, indicating that `Sec-CH-Prefers-Color-Scheme` is considered a [critical client hint](/en-US/docs/Web/HTTP/Client_hints#critical_client_hints).
+
+```http
+HTTP/1.1 200 OK
+Content-Type: text/html
+Accept-CH: Sec-CH-Prefers-Color-Scheme
+Vary: Sec-CH-Prefers-Color-Scheme
+Critical-CH: Sec-CH-Prefers-Color-Scheme
+```
+
+> **Note:** We've also specified `Sec-CH-Prefers-Color-Scheme` in the {{httpheader("Vary")}} header to indicate that responses should be separately cached based on the value of this header (even if the URL stays the same).
+> Each header listed in the `Critical-CH` header should also be present in the `Accept-CH` and `Vary` headers.
+
+The client automatically retries the request (due to `Critical-CH` being specified above), telling the server via `Sec-CH-Prefers-Color-Scheme` that it has a user preference for dark content:
+
+```http
+GET / HTTP/1.1
+Host: example.com
+Sec-CH-Prefers-Color-Scheme: "dark"
+```
+
+The client will include the header in subsequent requests in the current session, unless the `Accept-CH` changes in responses to indicate that it is no longer supported by the server.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Client hints](/en-US/docs/Web/HTTP/Client_hints)
+- [`prefers-color-scheme` CSS Media Query](/en-US/docs/Web/CSS/@media/prefers-color-scheme)
+- [User-Agent Client Hints API](/en-US/docs/Web/API/User-Agent_Client_Hints_API)
+- [Improving user privacy and developer experience with User-Agent Client Hints](https://web.dev/user-agent-client-hints/) (web.dev)
+- {{HTTPHeader("Accept-CH")}}
+- [HTTP Caching > Varying responses](/en-US/docs/Web/HTTP/Caching#varying_responses) and {{HTTPHeader("Vary")}}

files/en-us/web/http/headers/sec-ch-prefers-reduced-motion/index.md

@@ -85,6 +85,7 @@ The client will include the header in subsequent requests in the current session
 ## See also
 
 - [Client hints](/en-US/docs/Web/HTTP/Client_hints)
+- [`prefers-reduced-motion` CSS Media Query](/en-US/docs/Web/CSS/@media/prefers-reduced-motion)
 - [User-Agent Client Hints API](/en-US/docs/Web/API/User-Agent_Client_Hints_API)
 - [Improving user privacy and developer experience with User-Agent Client Hints](https://web.dev/user-agent-client-hints/) (web.dev)
 - {{HTTPHeader("Accept-CH")}}