This specification, in conjunction with the Events Module, is intended address the problem of device-, OS-, and localization-independent control of web content. See the introduction for background and usage examples.

Introduction

The primary goal of IndieUI User Context is to provide authorized web applications access to information about a user's relevant settings and preferences, to provide the best possible experience to all users. Some complex web applications can provide a much better experience if given access to information such as a user's preferred color, font, screen, and even *restricted* assistive technology settings such as a preference to render captions, or whether a screen reader is active. General web pages developed using best practices may never need access to restricted user settings, but complex web applications can utilize this information to enhance the performance and user interface.

There are privacy implications to providing any user-specific information to a third-party such as a web site, so a critical part of this specification defines how user agents and web browsers must prevent unauthorized access to user information, including methods to prevent access from parties interested in abusive uses such as "fingerprinting" by marketers. The IndieUI Working Group members believe we've provided a reasonable level of privacy with an API that prevents web sites from being able to detect a difference between a default setting and non-default setting that is not shared with the requesting site.

This section defines feature keys for user settings for use with the UserSettings interface. Some keys can also be accessed as Media Features using syntax defined in the CSS Media Queries specification. User Agents SHOULD implement an access control mechanism that allows users to restrict access to senesitive information requested via the userSettings() or matchMedia() methods of the Window interface, or from the @media selector in CSS. The specification below defines feature keys for user settings that can be requested through a new extension to the Window interface. Some keys can also be accessed as new "Media Features" to detect user settings, using existing syntax defined in the CSS Media Queries specification. Because this approach relies so heavily on features that overlap with work maintained by the CSS Working Group and Web Applications Working Group, it is possible that portions or all of this specification may move under the purview these other groups. At a minimum, the IndieUI Working Group requests guidance and a collaborative working relationship with CSS and WebApps.

Todo: Move these to the refs section and link them here:
http://www.w3.org/TR/css3-mediaqueries/

Extension to the Window Interface

Need to note why we could not use the standard addEventListener here. It would have either required a new event for every key (onUserFontSizeChanged, etc) or it would have not allowed authors to scope the preferences they were interested in (onUserSettingChange), and therefore prompted excessive callbacks, user prompts, etc.

DOMstring? userSetting()

Description TBD (esp re: privacy and fingerprinting, and prompt access for certain parameters on a per-domain basis, similar to location sharing)

						// example of settings keys defined within the IndieUI User Context specification.
						window.userSetting('user-font-size'); // returns computed value in CSS pixels, e.g. '16px'
						window.userSetting('subtitles'); // e.g. returns 'display' if the user wants to see subtitles/captions; otherwise returns 'none'
						
						// example of taxonomy- or vendor-prefixed settings proposals, intended for standardization.
						window.userSetting('-webkit-foo');
						window.userSetting('-moz-foo');
DOMString key
Identifying key for the preference value to be returned. User Agents MAY support prefixed keys for vendor-proposed or implementation-specific settings, or another external taxonomy.
void addUserSettingListener()
DOMString key
UserSettingListener callback
void removeUserSettingListener()
DOMString key
UserSettingListener callback

Standard vendor prefixes (ie, moz, o, webkit) are reserved. Any additional implementation, host language, or external taxonomy identifiers may be defined in a supplemental working group document.

UserSettingListener Callback Interface

void handleUserSettingChanged()
DOMString key
Key name for the requested user setting. E.g. 'user-font-size' or 'subtitles'

Privacy Model

Todo: Further explain how the privacy model works: when user prompted, window.userSetting() or window.matchMedia() return the default value or null immediately, and only provide the updated match ansynchronously through handleUserSettingChanged() and matchMedia().addEventListener, or on subsequent requests to matchMedia().matches (e.g. on page reload) so there is never any detectable difference between "No" and "You don't need to know." A restricted @media block never prompts unless both the @media block and an included selector matches.

Todo: Document way justification string may be defined by a meta tag in the document head, such as:
<meta name="userMediaSettings" content="Used to enable captions and display them in your preferred font size and color.">

Restriction Categories

none
No category defined (default value).
userColors
User settings related to color preferences. No default restriction.
userFonts
User settings related to type and font preferences. No default restriction.
userMediaSettings
User settings related to media alternatives such as captions/subtitles, audio description, etc. Default suggested restriction is to prompt the user for permission.
userScreenReaderSettings
User settings related to screen readers. Default restriction is to prompt the user with a justification provided by the requesting web site author.

Example Restriction UI

In the following example, the web author attempts to query two restricted user settings using two different techniques. For the sake of the example, assume the user's setting do match the specified queries.

					// Query matches if screen reader is enabled and user's privacy settings allow the match.
					var mediaQueryList = window.matchMedia('screen and (screenreader)');
					var mediaMatch = mediaQueryList.matches;

					// The following is equivalent to the previous MQ approach, but uses the window.userSetting().
					// window.userSetting will likely be the preferred interface for accessibing these settings 
					// through JavaScript, but the matchMedia syntax can be more terse for complex queries.
					var setting = window.userSetting('screenreader');
					var settingMatch = (setting === 'active') ? true : false;

					// Note: in conforming implementations, these boolean values will either both be true, or both be false.
					if (mediaMatch || settingMatch) {
					    console.log('A screen reader is active and the user prefers audio descriptions.');
					} else {
					    console.log('The settings do not match, or the user has chosen to not share that information.');
					}

Depending on the user's privacy settings and implementation details of the user agent, there are a number of outcomes, according to the following, normative requirements.

User Agent Requirements for Restricted User Settings

To avoid privacy concerns, User Agents MUST immediately return the default value for any restricted features that will result in a user prompt. If and when the user chooses to share settings from the relevant category with the requesting page, the web page author can handle a user setting change callback, or make a subsequent request to the userSetting() method of the Window object.

Example "Prompt with Justification" Dialog

In the following example dialog mockup, the web author has requested subtitles and/or subtitle-languages settings. The author has also provided a justification string for the userMediaSettings category using the following markup.

						<meta name="userMediaSettings" content="Example Site uses your media settings to automatically enable captions or subtitles in your preferred language.">

A user agent may render the prompt a number of ways, such as a non-blocking notification or a modal dialog.

Example dialog prompting user to confirm or deny access to media player settings.
Example dialog displaying site URL, details of the settings requested, an author-provided justification string, and buttons labeled Allow and Deny. Share media player settings with https://www.example.com? Example Site uses your media settings to automatically enable captions or subtitles in your preferred language. Allow Deny

Example restricted call to window.userSettings()

The following example illustrates the code path that is executed when a user with a preference for audio descriptions visits a web page that uses window.userSetting() to automatically enable the secondary audio track at load time.

						
						// Author defines a function to handle changes of the audioDescription setting.
						function handleAudioDescriptionChanged(key, value) {
						    if (key === 'audio-description' && value !=== 'none') {
						        // User has shared that audio descriptions should be presented.
						        // Enable the "descriptive audio" track in the video. 
						    } else {
						        // Set to default. Audio descriptions are off, 
						        // or the user has chosen to not share this setting.
						        // Authors should still provide a way to enable the
						        // audio description track in the video player interface.
						    }
						}

						/*
						When the author first attempts to check the setting, the user agent will 
						determine that this is a restricted setting, and immediately return the default 
						value or null, so the first call to this method on the initial page load will 
						never result in audio descriptions being enabled.

						Note: The immediate return is critical to prevent blocking threads, as well as
						eliminating potential abuse by fingerprinting scripts attempting to determine 
						uniqueness using execution time of the synchronous call to window.userSetting().
						*/

						// get the setting value
						var audioDescriptionSetting = window.userSetting('audio-description');

						// and explicitly call the handler the first time, because there is no callback yet
						handleAudioDescriptionChanged('audio-description', audioDescriptionSetting);

						/*
						Even though the setting returns the default value immediately, the user will be 
						prompted to decide whether or not to share their media alternative settings with 
						the requesting web site. 

						The web author can register for a change listener on this setting, and the handler 
						will be called asynchronously once the user agrees to share their media settings.
						*/
						window.addSettingListener('audio-description', handleAudioDescriptionChanged);

						// Note: Subsequent page loads should not cause the user to be prompted again.

User Agent Requirements for Restricted Media Queries

To avoid privacy concerns, User Agents MUST immediately match the default value of the media query for any restricted features that will result in a user prompt. If and when the user chooses to share settings from the relevant category with the requesting page, the web page author can receive a mediaQueryListChanged event, and make a subsequent request of the matches property of the MediaQueryList.

Example restricted call to window.matchMedia()

Todo: Add code example.

Example restricted use of @media block in CSS

Todo: Add code example.

Settings Keys and Related Media Feature counterparts

This section defines feature keys for user settings for use with the UserSettings interface. Some keys can also be accessed as Media Features using syntax defined in the CSS Media Queries specification. User Agents SHOULD implement an access control mechanism that allows users to restrict access to senesitive information requested via the userSettings() or matchMedia() methods of the Window interface, or from the @media selector in CSS. Todo: link these the the relevant portions of the access control extension.

The features are grouped by restriction categories (e.g. type settings, media settings, etc.) that define related media features and recommended default restriction levels.

Need a setting for whether full keyboard access is enabled (e.g. related to Safari "focus all controls" setting, or any touch screen device without a keyboard or Tab-like capability)

User Color Settings

Restriction Category (IDL)
userColors
Suggested User Agent Restriction
none

Color settings are not be restricted by default from the requesting page, primarily because a site can figure out most of this information using some creative CSS and JavaScript. These keys are therefore primarily intended as convenience accessors so that web authors can more easily provide adaptive interfaces that work well for all users. The display inversion feature is not currently detectable, but does not represent a major concern for privacy or fingerprinting since it is unlikely that most individuals will have this setting enabled all the time.

Key: user-color

Has Associated Media Feature
Yes
Returns
String values matching the associated media feature values.
Restriction Category (IDL)
userColors
Associated Media Feature: user-color
Value
<HSLA Color>
Applies to
visual media
Accepts min/max prefixes
No
Accepts hue/saturation/luminosity/alpha suffixes
Yes
Restriction Category (IDL)
userColors

See user-background-color and user-subtitle-background-color for examples of how the color media queries might be used with HSLA suffixes.

Key: user-background-color

Has Associated Media Feature
Yes
Returns
String values matching the associated media feature values.
Restriction Category (IDL)
userColors
Associated Media Feature: user-background-color
Value
<HSLA Color>
Applies to
visual media
Accepts min/max prefixes
No
Accepts hue/saturation/luminosity/alpha suffixes
Yes
Restriction Category (IDL)
userColors

In this example, the user-defined color and background color are defined through a user style sheet or other means, so override the site theme to respect the user's colors.

								@media (user-color) and (user-background-color) {
								    html, body {
								        /* Syntax for the user-pref variables to be specified in one of the CSS 4 modules. */
								        color: user-pref(color);
								        background-color: user-pref(background-color);
								    }
								}

In this example, the user-defined background color is dark (luminosity less than 40%), so the author adjusts the site logo element to use an image that looks better on darker background colors.

								/* Use default logo that looks good on lighter background colors. */
								.logo { background-image: url(./img/logo_light.png);}

								/* Note: this example uses the greater-than/less-than syntax likely to be adopted by CSS4. */
								@media (user-background-color-luminosity < 40) {
								    /* User background color is dark; use logo variant that looks better on dark colors. */
								    .logo { background-image: url(./img/logo_dark.png); }
								}

In this example, the user-defined background color matches a warm palette (hue is not between 100 and 280; a.k.a. not green, blue, or blue-violet), so the author could adjust the rest of the site theme to be complementary.

								/* Note: this example uses the greater-than/less-than syntax likely to be adopted by CSS4. */
								@media (user-background-color-hue < 100) or (user-background-color-hue > 280) {
								    /* User background color palette is red-violet, red, orange, or yellow. */
								    /* This is example is admittedly contrived, and exists mainly to show possibilities. */
								}

Key: colors-inverted

Web authors SHOULD NOT re-invert foreground and background colors based on this setting, but MAY choose to double-invert some content, such as photographs.

Has Associated Media Feature
Yes
Returns
Boolean indicating whether the display colors are currently inverted by the operating system or user agent.
Restriction Category (IDL)
userColors
Associated Media Feature: colors-inverted
Value
inverted | [none]
Applies to
visual media
Accepts min/max prefixes
No
Restriction Category (IDL)
userColors

In this example, the hardware display rendering is inverted, so the web app could double-invert foreground image and video content, which usually looks strange while inverted. This would leave text foreground color, all background colors, and background styles inverted to adhere to user setting.

								@media (colors-inverted) {
								    img, video {
								        filter: invert(100%);
								    }
								}
Screen shot of Twitter mobile web site displayed on iOS with screen colors inverted. Mock up of previous screen shot with user profile images double-inverted, to achieve a more natural rendering and skin color.
Everything in the first screen shot, including the user profile image, is inverted so skin tones are unnatural. A web application could choose to double-invert content images, as is done in the second screen shot.

In this example, the hardware display rendering is inverted, so the web app could hide elements styles that resemble "shadows" of physical light, which by default look like white glows while inverted. This media query allows authors to disable settings that don't make sense when the physical display pixels are inverted.

								@media (colors-inverted) {
								    .page {
								        box-shadow: none;
								    }
								    .pagecurl {
								        background-image: none;
								    }
								}

Note: Privacy and fingerprinting concerns related to this media feature are minimal, since it is unlikely that most individuals will have this setting enabled all the time. For example, due to personal preference or situational context, some individuals use this as a manual quick toggle to temporarily view text content in a light-on-dark color scheme as opposed to a dark-on-light default.

Additional anecdotal evidence of how useful this could be as a media query can be found on Stack Exchange UX.

Concepts related to colors-inverted

Key: user-contrast

Has Associated Media Feature
Yes
Returns
Floating point number value between -1.0 and 1.0, representing the software contrast setting of the user's operating system. A value of 0.0 represents no contrast modification to the display (normal), and 1.0 represents the highest possible contrast modification (could be used to Microsoft's "high contrast" mode). A negative number (uncommon) represents a lower-than-average contrast. User Agents SHOULD NOT use a positive value to represent hardware display contrast, as this value is reserved for assistive contrast modes. User Agents MAY use a negative value to represent lower-than-average contrast in a hardware display.
Restriction Category (IDL)
userColors
Associated Media Feature: user-contrast
Value
<Number> between -1.0 and 1.0
Applies to
visual media
Accepts min/max prefixes
Yes
Restriction Category (IDL)
userColors

This example illustrates how Microsoft's implementation-specific -ms-high-contrast proposal can be replaced by three media features that are not implementation-specific.

Currently Microsoft does not impose any restrictions on the -ms-high-contrast media feature, but it's possible the user-contrast setting may end up in a restricted category if it's determined to expose the user to privacy or fingerprinting implications.

								/*
								adjusting to cover both the Microsoft proposal as well 
								as other platforms that have a slider value for color variants 
								*/

								/* -ms-high-contrast: active; would be equivalent to: */
								@media (user-contrast: 1) {}

								/* a variant query of the same media feature would match both Microsoft's */
								/* binary setting and other platform's variable contrast settings */
								/* Note: this example uses the greater-than/less-than syntax likely to be adopted by CSS4. */
								@media (user-contrast > 0) {}

								/* -ms-high-contrast: black-on-white; would be equivalent to: */
								@media (user-contrast: 1) {}
								       and (user-color: black)
								       and (user-background-color: white) {}

								/* -ms-high-contrast: white-on-black; would be equivalent to: */
								@media (user-contrast: 1) 
								       and (user-color: white) 
								       and (user-background-color: black) {}

								/* -ms-high-contrast: white-on-black; could also be written to use the HSLA color suffixes: */
								@media (user-contrast: 1) 
								       and (user-color-luminosity: 100) 
								       and (user-background-color-luminosity: 0) {}

								/* -ms-high-contrast: none; would be equivalent to the default value: */
								/* No media query is required here b/c it's already the default value. */
								/* @media (user-contrast: 0) {} */

Microsoft's current implementation of "high contrast" would only ever return 0.0 or 1.0, but other platforms support variable contrast increases that would result in a intermediary value like 0.42, or 0.7, which could be matched using the CSS3 min/max prefixes, or the CSS4 greater-than/less-than syntax.

Key: monochrome

Has Associated Media Feature
Yes
Returns
Integer representing number of bits per pixel in a monochrome frame buffer. If the device is not a monochrome device, the output device value will be 0.
Restriction Category (IDL)
userColors
Associated Media Feature: monochrome

The monochrome media feature is defined in CSS3.

User Type/Font Settings

Restriction Category (IDL)
userFonts
Suggested User Agent Restriction
none

Type settings are not restricted by default from the requesting page, because a site can figure out all of this information by creatively using CSS and JavaScript. These keys are therefore primarily intended as convenience accessors so that web authors can more easily provide adaptive interfaces that work well for all users.

Key: user-font-size

Has Associated Media Feature
Yes
Returns
Number representing the user's current default font size of root element, prior to applying page styles. User Agents MUST return the value translated to CSS pixels, e.g. 14, not '14px' or '1.4em'
Restriction Category (IDL)
userFonts
Associated Media Feature: user-font-size
Value
<number>
Applies to
visual media
Accepts min/max prefixes
Yes
Restriction Category (IDL)
userFonts
							/* Default layout uses 2 columns */
							main {
							    columns: 2;
							}

							/* But if the user's default font size (from browser text zoom setting or... */
							/* user style sheet...) is larger than 32px, drop the columns. */
							/* Note: the CSS3 syntax is (min-user-font-size: 32) */
							/* Note: this example uses the greater-than/less-than syntax likely to be adopted by CSS4. */
							@media (user-font-size > 32) { 
							    main {
							        columns: auto;
							    }
							}

Key: user-minimum-font-size

Has Associated Media Feature
Yes
Returns
Number representing the user's minimum allowed font size. User Agents MUST return the value translated to CSS pixels, e.g. 9, not '9px' or '0.9em'
Restriction Category (IDL)
userFonts
Associated Media Feature: user-minimum-font-size
Value
<number>
Applies to
visual media
Accepts min/max prefixes
Yes
Restriction Category (IDL)
userFonts

Key: user-line-height

Has Associated Media Feature
No
Returns
Number as a unitless multiplier; equivalent to unitless 'Number' value for CSS 'line-height' property. e.g. 1.2, not '1.2em' or '12px'
Restriction Category (IDL)
userFonts

Key: user-letter-spacing

Has Associated Media Feature
No
Returns
Unit TBD; this should probably also be a calculated CSS pixel value equivalent to default or user value for CSS 'letter-spacing' property.
Restriction Category (IDL)
userFonts

Key: user-word-spacing

Has Associated Media Feature
No
Returns
Unit TBD; this should probably also be a calculated CSS pixel value equivalent to default or user value for CSS 'word-spacing' property.
Restriction Category (IDL)
userFonts

In addition to font-size, which is commonly adjusted by mainstream users, line-height, letter-spacing, and word-spacing can be especially important for users with cognitive impairments such as dyslexia and ASD, so it's important to respect a user's default settings.

User Media Settings

Restriction Category (IDL)
userMediaSettings
Suggested User Agent Restriction
prompt

Key: subtitles

Web authors using a native video player SHOULD allow subtitles to be displayed natively. Web authors using a custom subtitle view SHOULD display the custom-rendered subtitles based on this setting.

Has Associated Media Feature
No
Returns
Boolean value indicating whether subtitles or captions are displayed (true) or not displayed (false) in native video players.
Restriction Category (IDL)
userMediaSettings

Key: subtitle-languages

Has Associated Media Feature
No
Returns
DOMString of languages in order of preference. Users Agents MUST format the string as a space-separated list of ISO-639 language codes, that may be optionally hyphenated to include ISO-3166 country codes.
Restriction Category (IDL)
userMediaSettings

For example, a native Mexican Spanish speaker living in the United States may have a language preference of "es-mx es en-us en" indicating a preference order for Mexican Spanish, any Spanish, US English, and finally any English dialect.

Key: subtitle-type

Has Associated Media Feature
No
Returns
DOMString of type of subtitles or captions in order of preference. Users Agents MUST format the string as a space-separated list of the following tokens: sdh, cc, or standard
Restriction Category (IDL)
userMediaSettings

Necessary to match preference for subtitles for the deaf and hard of hearing (SDH) over default dialogue-only subtitles, but the preference for closed captions (CC) versus SDH may not be necessary. SDH appears to be generally preferred over CC when available, and a preference for SDH could indicate an implicit preference for CC over dialogue-only subtitles when CC is available but SDH is not.

Key: user-subtitle-color

Has Associated Media Feature
Yes
Returns
String values matching the associated media feature values.
Restriction Category (IDL)
userMediaSettings
Associated Media Feature: user-subtitle-color
Value
<HSLA Color> | [none]
Applies to
continuous, visual media
Accepts min/max prefixes
No
Accepts hue/saturation/luminosity/alpha suffixes
Yes
Restriction Category (IDL)
userMediaSettings

See user-background-color and user-subtitle-background-color for examples of how the color media queries might be used with HSLA suffixes.

Key: user-subtitle-background-color

Has Associated Media Feature
Yes
Returns
String values matching the associated media feature values.
Restriction Category (IDL)
userMediaSettings
Associated Media Feature: user-subtitle-background-color
Value
<HSLA Color> | [none]
Applies to
continuous, visual media
Accepts min/max prefixes
No
Accepts hue/saturation/luminosity/alpha suffixes
Yes
Restriction Category (IDL)
userMediaSettings

In this example, the user-defined subtitle background color is not sufficiently opaque to to prevent the video noise from making the captions difficult to read, so add a text shadow.

								/* Note: this example uses the greater-than/less-than syntax likely to be adopted by CSS4. */
								@media (user-subtitle-background-color-alpha < 20) and (user-subtitle-color-luminosity > 50) {
								    .customRenderedCaptions {
								    	text-shadow: 1px 1px 2px black; 
								    }
								}

See user-background-color and user-subtitle-background-color for examples of how the color media queries might be used with HSLA suffixes.

Key: audio-description

Has Associated Media Feature
No
Returns
display | [none]
Restriction Category (IDL)
userMediaSettings

Returns a user's preference to be presented with an alternate or supplemental audio track describing the information presented visually.

Audio descriptions are also sometimes referred to as "descriptive audio" tracks.

Need a more appropriate true value than "display"; possibly "prefer", "selected", etc.

Screen Reader Settings

Restriction Category (IDL)
userScreenReaderSettings
Suggested User Agent Restriction
prompt with author-provided justification

User Agents MUST NOT implement high security features like screenreader settings until the user privacy model is implemented. User Agents MUST allow users to control sharing of prompted settings on a per-domain basis.

Web authors SHOULD NOT request any keys in this category unless the knowledge is essential to the operation of the web application, and web authors MUST provide a justification for the request as defined in @@ section.

Editorial Note on User Privacy

Due to community feedback related to privacy, this feature may be marked as at-risk or removed. The working group acknowledges its usefulness in complex web applications such as enterprise document-editing suites, but also acknowledges the fact that its utility may be easily misunderstood or potentially misused.

For example, the typing echo or other verbosity settings would be useful today, for sites such as Google Docs and iWork for iCloud. These applications use custom display views that are not able to be made accessible through conventional means, so speech output is controlled via live region announcements. The web application does not otherwise have access to user settings such as typing echo, so without access to this feature, the web application could not mimic the user's preferred output.

One potential misuse is for user metrics or tracking. Even with the best of intentions, this is a potentially harmful misuse of the API. There are currently very strict user privacy model requirements to implement this feature in a reasonably safe and secure way, but if the working group is not comfortable in the implementation's ability to sufficiently prevent this type of misuse, we will remove the feature.

Key: screenreader

Returns whether a screen reader is currently active or not (none).

Has Associated Media Feature
Yes
Returns
Token value indicating whether or not a screen reader is currently active or in use (active), or none otherwise.
Restriction Category (IDL)
userScreenReaderSettings
Associated Media Feature: screenreader
Value
active | [none]
Applies to
interactive media
Accepts min/max prefixes
No
Restriction Category (IDL)
userScreenReaderSettings

Key: screenreader-typing-echo

Returns a value indicating whether typing in text fields causes a screen reader echos whole words, characters, both, or none.

Has Associated Media Feature
No
Returns
words | characters | both | [none]
Restriction Category (IDL)
userScreenReaderSettings

Todo: Probably need additional categories for screen magnifiers (active/none, scale factor), switch control software (active/none), and the more general "api-compatible" key which could be used for automation scripts in addition to real assistive technology.

Settings Keys List (alphabetical)

Media Features List (alphabetical)