user_preferences member
+ + The `user_preferences` member of the [=application manifest=] is an + object that can be used to override values of manfiest members depending + on which user preferences are set. It has the following members: +
++ This list of members is expected to expand in the future to include + other user + preference media features such as contrast and + forced-colors, + as defined in CSS. +
++ The user agent SHOULD use the override values instead of the value of + the corresponding member defined at the top level of the manifest. +
++ To process the `user_preferences` member, given + [=ordered map=] |json:ordered_map|, [=ordered map=] |manifest:ordered map|, + run the following during the [=application manifest/processing + extension-point=] in [=processing a manifest=]: +
+color_scheme
+ member
+ + The [=user_preferences=] `color_scheme` member is an object that + contains the overrides for color scheme preferences. It has the + following members: +
+
+ The dark member
+ specifies the manifest overrides to use when the user prefers a
+ dark theme.
+
+ The light member
+ specifies the manifest overrides to use when the user prefers a
+ light theme.
+
+ To process the `color_scheme` member, given [=ordered map=] + |json_user_preferences:ordered_map|, [=ordered map=] + |manifest_user_preferences:ordered map|, run the following: +
++ The proterties that [=user_preferences=] can override in the + [=manifest override object=] are: +
++ Each manifest override object is a generic object value + that allows for certain manifest properties to be overridden within + a particular context. +
+The structure of a [=manifest override object=] is as follows:
+
+ {
+ "context_key": {
+ "property": "new value"
+ }
+ }
+
+ + Each manifest property that accepts a [=manifest override object=] + as its value will define the contexts it supports and which + properties it supports overriding. User agents MUST ignore any contexts + that are not supported by the property as well as any override + properties not explicitly allowed within it. +
++ When the manifest property’s context is applicable, the value of each + allowable override will be used in place of the original value defined + in the Manifest. +
++ Redefined array items will be overridden in the order they are authored. + When redefining objects (e.g., [=manifest/shortcuts=], [=manifest/icons=]), + authors will only be able to redefine specific properties of that object. + In order to ensure all overrides are applied correctly, the order must + match the original array (i.e., each [=manifest/shortcut=] must be redefined + in order, as must their icons, if they also require re-definition). +
+ Redefined array items must also be equal in number to the array being + overridden. If there is a mismatch in the number of items in either array, + any excess items will be ignored. This is only an issue if the original + array has more items than the override array, because any excess items + within the original array will not be re-defined. + ++ When there is a conflict because two different properties are attempting + to override the same value in their respective active contexts, the one + defined last will win. By way of example, consider the following: +
+
+ {
+ "lang": "en-US",
+ "icons": [
+ {
+ "src": "icon.png",
+ "sizes": "128x128",
+ "type": "image/png"
+ }
+ ],
+ "translations": {
+ "es": {
+ "icons": [
+ {
+ "src": "icon-es.png"
+ }
+ ]
+ }
+ },
+ "user_preferences": {
+ "color_scheme": {
+ "dark": {
+ "icons": [
+ {
+ "src": "icon-dark.png"
+ }
+ ]
+ }
+ }
+ }
+ }
+
+ + In this example, if the user’s primary language is Español, but + their preferred color scheme was set to "dark", the icon supplied + would be the dark version and not the localized one. For this reason, + it is imperative that properties taking a [=manifest override object=] + as their value consider whether any other properties that also enable + overrides should be able to be redefined within them. In the above + example, the author’s intent would likely have been better realized + if `user_preferences` was put before `translations` and the localized + context block redefined the `user_preferences` value for that language: +
+
+ {
+ "lang": "en-US",
+ "icons": [
+ {
+ "src": "icon.png",
+ "sizes": "128x128",
+ "type": "image/png"
+ }
+ ],
+ "user_preferences": {
+ "color_scheme": {
+ "dark": {
+ "icons": [
+ {
+ "src": "icon-dark.png"
+ }
+ ]
+ }
+ }
+ },
+ "translations": {
+ "es": {
+ "icons": [
+ {
+ "src": "icon-es.png"
+ }
+ ],
+ "user_preferences": {
+ "color_scheme": {
+ "dark": {
+ "icons": [
+ {
+ "src": "icon-es-dark.png"
+ }
+ ]
+ }
+ }
+ }
+ }
+ },
+
+ }
+
+ + User agents MAY ignore any override properties they do not support. +
++ To apply a manifest override object, given [=ordered_map=] + |overrides:json|, [=ordered map=] + |manifest:ordered map|, and [=array=] |allowed_properties:array| run the following: +
+