User Preference Media Features Client Hints Headers

1. Introduction

CSS media queries, and specifically Media Queries 5 §  11. User Preference Media Features like prefers-color-scheme or prefers-reduced-motion, have a potentially significant impact on the amount of CSS that needs to be delivered by a page, and on the experience the user is going to have when the page loads.

High-traffic sites like search engines or news sites that wish to honor user preference media features like prefers-color-scheme and that inline CSS for performance reasons need to know about the preferred color scheme (or other user preference media features respectively) ideally at request time, so that the initial HTML payload already has the right CSS inlined.

Additionally, and specifically for prefers-color-scheme, sites by all means want to avoid a flash of inaccurate color theme.

This specification introduces a set of [CLIENT-HINTS] headers around user preference media features as defined by [MEDIA-QUERIES-LEVEL-5], which servers can opt-in to receive via the Client Hints infrastructure defined in [RFC8942].

1.1. Usage Example

1. The client makes an initial request to the server.

   GET / HTTP/1.1
   Host: example.com
   

2. The server responds, telling the client via Accept-CH that it accepts the Sec-CH-Prefers-Color-Scheme and the Sec-CH-Prefers-Contrast Client Hints, out of which as per Critical-CH it considers Sec-CH-Prefers-Color-Scheme a Critical Client Hint that it also varies the response on as conveyed by Vary.

   HTTP/1.1 200 OK
   Content-Type: text/html
   Accept-CH: Sec-CH-Prefers-Color-Scheme, Sec-CH-Prefers-Contrast
   Vary: Sec-CH-Prefers-Color-Scheme
   Critical-CH: Sec-CH-Prefers-Color-Scheme
   

3. The client then retries the request, telling the server via Sec-CH-Prefers-Color-Scheme that it has a user preference for dark-schemed content.

   GET / HTTP/1.1
   Host: example.com
   Sec-CH-Prefers-Color-Scheme: "dark"
   

4. The server can then tailor the response to the client’s preferences accordingly and, for example, inline the CSS responsible for the dark theme into the response body.

2. User Preference Media Features

User preference media features consist of a name (like prefers-reduced-motion) and allowed values (like no-preference or reduce. Each client hint header field defined in the following is represented as [draft-ietf-httpbis-header-structure-19] object containing an items whose value is a string. The ABNF (Augmented Backus-Naur Form) for each header is given below. It is the expectation of the author that these client hints will commonly be used as [draft-davidben-http-client-hint-reliability-02].

2.1. Sec-CH-Prefers-Reduced-Motion

The Sec-CH-Prefers-Reduced-Motion high-entropy client hint is modeled after the prefers-reduced-motion user preference media feature as defined in Media Queries 5 § 11.1 Detecting the desire for less motion on the page: the prefers-reduced-motion feature. The ABNF syntax for this header header field is as follows:

Sec-CH-Prefers-Reduced-Motion = "no-preference" / "reduce"

2.2. Sec-CH-Prefers-Reduced-Transparency

The Sec-CH-Prefers-Reduced-Transparency high-entropy client hint is modeled after the prefers-reduced-transparency user preference media feature as defined in Media Queries 5 § 11.2 Detecting the desire for reduced transparency on the page: the prefers-reduced-transparency feature. The ABNF syntax for this header header field is as follows:

Sec-CH-Prefers-Reduced-Transparency = "no-preference" / "reduce"

2.3. Sec-CH-Prefers-Contrast

The Sec-CH-Prefers-Contrast high-entropy client hint is modeled after the prefers-contrast user preference media feature as defined in Media Queries 5 § 11.3 Detecting the desire for increased or decreased color contrast from elements on the page: the prefers-contrast feature. The ABNF syntax for this header header field is as follows:

Sec-CH-Prefers-Contrast = "no-preference" / "less" / "more" / "custom"

2.4. Sec-CH-Forced-Colors

The Sec-CH-Forced-Colors high-entropy client hint is modeled after the forced-colors user preference media feature as defined in Media Queries 5 § 11.4 Detecting Forced Colors Mode: the forced-colors feature. The ABNF syntax for this header header field is as follows:

Sec-CH-Forced-Colors = "none" / "active"

2.5. Sec-CH-Prefers-Color-Scheme

The Sec-CH-Prefers-Color-Scheme high-entropy client hint is modeled after the prefers-color-scheme user preference media feature as defined in Media Queries 5 § 11.5 Detecting the desire for light or dark color schemes: the prefers-color-scheme feature. The ABNF syntax for this header header field is as follows:

Sec-CH-Prefers-Color-Scheme = "light" / "dark"

3. Feature Registry

3.1. Client hints token

This document extends the client hints token with the following byte-lowercase representation of one of Sec-CH-Prefers-Reduced-Motion, Sec-CH-Prefers-Reduced-Transparency, Sec-CH-Prefers-Contrast, Sec-CH-Prefers-Forced-Colors, Sec-CH-Prefers-Color-Scheme.

3.2. Policy-controlled features

This document extends the policy-controlled client hints features with the following policy-controlled features:

• ch-prefers-reduced-motion which has a default allowlist of 'self'

• ch-prefers-reduced-transparency which has a default allowlist of 'self'

• ch-prefers-contrast which has a default allowlist of 'self'

• ch-prefers-forced-colors which has a default allowlist of 'self'

• ch-prefers-color-scheme which has a default allowlist of 'self'

4. Privacy Considerations

The User Preference Media Features Client Hint header exposes data at the HTTP request level that is otherwise attainable and/or detectable using JavaScript and CSS as defined in [MEDIA-QUERIES-LEVEL-5]. By providing this data at the request level, the server gains the ability to customize the response based on the user’s preferences. Importantly, it does not grant the server access to any previously inaccessible information.

5. Security Considerations

The User Preference Media Features Client Hint header will only be available to HTTPS secure contexts. Additionally, the Security Considerations of [CLIENT-HINTS] and the Security Considerations of [draft-davidben-http-client-hint-reliability-02] likewise apply to this proposal.

6. Acknowledgements

Special thanks to Yoav Weiss and Mike Taylor for their technical input and suggestions that led to improvements to this specification.