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
Inline In Spec
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].

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 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 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 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 client hint is modeled after the forced-colors user preference media feature as defined in Media Queries 5 §11.5 Detecting a forced color palette: 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 client hint is modeled after the prefers-color-scheme user preference media feature as defined in Media Queries 5 §11.4 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"

2.6. Sec-CH-Prefers-Reduced-Data

The Sec-CH-Prefers-Reduced-Data client hint is modeled after the prefers-reduced-data user preference media feature as defined in Media Queries 5 §11.6 Detecting the desire for reduced data usage when loading a page: the prefers-reduced-data feature. The ABNF syntax for this header header field is as follows:

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

[savedata] already defines a Save-Data client hint header. Should the present spec then define Sec-CH-Prefers-Reduced-Data for consistency as an alias of Save-Data?

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, or Sec-CH-Prefers-Reduced-Data.

3.2. Policy-controlled features

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

4. 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.

5. Acknowledgements

Special thanks to Yoav Weiss for his 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.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

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/
[PERMISSIONS-POLICY]
Ian Clelland. Permissions Policy. ED. 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://tools.ietf.org/html/rfc2119
[SAVEDATA]
Yoav Weiss; Ilya Grigorik. Save Data API. Draft Community Group Report. URL: https://wicg.github.io/savedata/#save-data-request-header-field

Issues Index

[savedata] already defines a Save-Data client hint header. Should the present spec then define Sec-CH-Prefers-Reduced-Data for consistency as an alias of Save-Data?