User Preference Media Features Client Hints Headers

Draft Community Group Report,

This version:
https://wicg.github.io/user-preference-media-features-headers/
Issue Tracking:
GitHub
Editors:
(Google LLC)
(Google LLC)

Abstract

HTTP Client Hints defines an Accept-CH response header that servers can use to advertise their use of request headers for proactive content negotiation. This specification introduces a set of user preference media features client hints headers like Sec-CH-Prefers-Color-Scheme, which notify the server of user preferences that will meaningfully alter the requested resource, like, for example, through the currently preferred color scheme. These client hints will commonly also be used as critical client hints via the Critical-CH header.

Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

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:

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.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CLIENT-HINTS]
Ilya Grigorik; Yoav Weiss. HTTP Client Hints. RFC - Experimental (February 2021; No errata). URL: https://datatracker.ietf.org/doc/rfc8942/
[DRAFT-DAVIDBEN-HTTP-CLIENT-HINT-RELIABILITY-02]
David Benjamin. Client Hint Reliability. ID. URL: https://tools.ietf.org/html/draft-davidben-http-client-hint-reliability-02
[DRAFT-IETF-HTTPBIS-HEADER-STRUCTURE-19]
Mark Nottingham; Poul-Henning Kamp. Structured Field Values for HTTP. ID. URL: https://tools.ietf.org/html/draft-ietf-httpbis-header-structure-19
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[MEDIA-QUERIES-LEVEL-5]
Dean Jackson; et al. Media Queries Level 5. ED. URL: https://drafts.csswg.org/mediaqueries-5/
[MEDIAQUERIES-5]
Dean Jackson; et al. Media Queries Level 5. URL: https://drafts.csswg.org/mediaqueries-5/
[PERMISSIONS-POLICY-1]
Ian Clelland. Permissions Policy. URL: https://w3c.github.io/webappsec-permissions-policy/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[RFC8942]
I. Grigorik; Y. Weiss. HTTP Client Hints. February 2021. Experimental. URL: https://www.rfc-editor.org/rfc/rfc8942
MDN

Headers/Sec-CH-Prefers-Reduced-Motion

In only one current engine.

FirefoxNoneSafariNoneChrome108+
Opera?Edge108+
Edge (Legacy)?IENone
Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile?