Can I confirm the documentation updates required:

• in summary: this is a new manifest key theme_experiment providing for the properties: stylesheet, images, and properties. It enables developers to do two things:

• override page CSS and therefore align look of all pages with the browser theme.

• override the images used for icons in the browser UI and apply properties to those images, enabling the developer to more deeply customize the UI.
  It is supported on desktop Firefox only from version 63.

• manifest keys pages: add a new page for theme_experiment with the following content:

Type: Object
Mandatory: No
Example:

"theme_experiment": {
"stylesheet": "style.css", // optional
"colors": {
"popup_affordance": "arrowpanel-dimmed"
},
"images": {
"theme_toolbar": "toolbar-bgimage"
},
"properties": {
"toolbar_image_alignment": "toolbar-bgalignment"
}
}

Theme experiments enable to features:

• overriding the CSS of pages so that the presentation of pages more closely matches the theme applied to the browser UI.
• specification of new images to use as content within Firefox UI components, thus enabling the UI to be more deeply customized. MSyntax

The theme key is an object that takes the following properties:

• browser compatibility data: add a compatibility file for theme_experiment and include the properties stylesheet, images, and properties indicating their availability from Firefox for desktop version 63.

Sorry for not providing much detail in this bug. Here's a summary of how it works:

This feature allows defining new theme properties for styling parts of the Firefox interface that the built-in properties don't cover. One very important thing to note is that the feature is limited to Developer Edition and Nightly channels behind the extensions.legacy.enabled preference.

The stylesheet is injected inside the Firefox interface and lets you define CSS variables that can then be mapped in the colors, images and properties objects to new theme properties.

For example, I could have a style.css file which has:

#reload-button {
  fill: var(--reload-button-color);
}

(the #reload-button ID references to Firefox's internal code, and --reload-button-color is a name you make up).

and then in the manifest.json file, I could use:

"theme_experiment": {
  "stylesheet": "style.css",
  "colors": {
    "reload_button": "--reload-button-color"
  }
}

and you can use reload_button as any other theme property:

"theme": {
  "colors": {
    "reload_button": "orange"
  }
}

which would make the reload icon color orange. You can also use this property in browser.theme.update() like other property.

images and properties work pretty similarly to colors.

Without stylesheet, you can still use this feature to map internal CSS variables that Firefox defines (like --arrowpanel-dimmed) to new theme properties. There isn't an exhaustive list of those anywhere, since the feature is mostly about defining new theme properties using Firefox internals.

Though I think most of the usefulness from this feature would come from the stylesheet feature, given that it can inject arbitrary CSS into the Firefox UI and hence have a lot of power.

Note that this feature could change at any time (though it hasn't so far), since it's experimental and only exposed to Nightly/Developer Edition.

Please let me know if you have any questions :)

Hi Tim,

I've attached my work in progress writeup below, but also have some questions/requests:

1. given that you can't use this to release a theme, what is the purpose? Is it simply to give developers the option to play around? could it lead to a feature For the release version of Firefox?
2. why wasn't this done by providing a set of hidden/experimental properties in theme?
3. I'm still somewhat unclear what the advantage of defining the stylesheet given that all you appear to do is map a Firefox UI component ID to an arbitrary name which in there then is in turn mapped to an arbitrary name for a key view using theme. Why isn't it easier simply to map the Firefox UI component ID to the key property in theme_experiment ?
4. If you don't make use of the stylesheet, in your example would you define "colors": {"reload_button": "#reload-button"}?
5. Where can I find a list of/lookup/discover the Firefox UI component ID?

Thanks!

<table>
<tbody>
<tr>
<td>Type</td>
<td>Object</td>
</tr>
<tr>
<td>Mandatory</td>
<td>No</td>
</tr>
<tr>
<td>Example</td>
<td><pre>"theme_experiment": {
"stylesheet": "style.css",
"colors": {
"popup_affordance": "arrowpanel-dimmed"
},
"images": {
"theme_toolbar": "toolbar-bgimage"
},
"properties": {
"toolbar_image_alignment": "toolbar-bgalignment"
}
} </pre>
</td>
</tr>
</tbody>
</table>

This key enables new theme key properties for the Firefox interface to be defined. This is done by either creating a stylesheet that provides mapping between the Firefox internal ID for a UI element feature and an arbitrary … ( to be completed)

The stylesheet is injected inside the Firefox interface and lets you define CSS variables that can then be mapped in the colors, images and properties objects to new theme properties.

Without stylesheet, you can still use this feature to map internal CSS variables that Firefox defines (like --arrowpanel-dimmed) to new theme properties. There isn't an exhaustive list of those anywhere, since the feature is mostly about defining new theme properties using Firefox internals.

Note: This key is only available for use in Firefox Developer Edition and Firefox Nightly channels and requires the extensions.legacy.enabled preference to be enabled.

** Warning**: This feature is experimental and could be subject to change.

Syntax

The theme key is an object that takes the following properties:

A list of UI element Firefox internal IDs is available (where?)

Examples

This example uses a stylesheet named style.css to provide the ability to define a color for the browser reload button in the theme key.

The stylesheet defines:

#reload-button {
  fill: var(--reload-button-color);
}

where #reload-button is the Firefox internal ID for the reload button and --reload-button-color is an arbitrary name.

In the manifest.json file, --reload-button-color is then mapped to the name to be used in the theme colors property:

"theme_experiment": {
  "stylesheet": "style.css",
  "colors": {
    "reload_button": "--reload-button-color"
  }
}

Then reload_button is used in the same way as any other theme property:

"theme": {
  "colors": {
    "reload_button": "orange"
  }
}

This has the effect of making the reload icon orange.

(add image)

This property can also be used in browser.theme.update(). images and properties work in a similar way to colors.

given that you can't use this to release a theme, what is the purpose? Is it simply to give developers the option to play around? could it lead to a feature For the release version of Firefox?

Same purpose as WebExtension experiments, propose new theming API features for inclusion in Firefox.

why wasn't this done by providing a set of hidden/experimental properties in theme?

We wouldn't be able to cover everyone's needs, so it's better that extension developers define the experiment themselves.

I'm still somewhat unclear what the advantage of defining the stylesheet given that all you appear to do is map a Firefox UI component ID to an arbitrary name which in there then is in turn mapped to an arbitrary name for a key view using theme. Why isn't it easier simply to map the Firefox UI component ID to the key property in theme_experiment ?

The mapping maps a key property in theme_experiment to a Firefox UI CSS variable, to a not UI element/component ID. The stylesheet lets you define those Firefox UI CSS variables.

Also, CSS variables can be used in a more creative way then the example I showed above, a more crazy example would be:

#reload-button {
  fill: var(--reload-button-color);
}

#reload-button:hover {
  background-color: var(--reload-button-color);
  fill: white;
}

If you don't make use of the stylesheet, in your example would you define "colors": {"reload_button": "#reload-button"}?

That simply wouldn't work. The value needs to be defined CSS variable, hence why the stylesheet is useful, since it allows to define new CSS variables.
If you don't make use of the stylesheet, you can only map to CSS variables (not component IDs) that Firefox already defines internally. There's unfortunately not centralized place to find all the CSS vars, but by inspecting through the browser toolbox, it's possible to find them.

https://developer.mozilla.org/en-US/docs/Tools/Browser_Toolbox

Where can I find a list of/lookup/discover the Firefox UI component ID?

You can inspect the Firefox interface using the Browser Toolbox.

Hi Tim, thanks for your feedback. Here is my final draft for the MDN content. do you have any further comments?

This key enables experimental theme key properties for the Firefox interface to be defined. These experiments are a precursor to proposing new theme features for inclusion in Firefox. Experimentation is done by:

• creating a stylesheet that defines mappings between internal IDs for Firefox UI element features and arbitrary CSS variables. The CSS variables are then mapped in the colors, images and properties objects to new theme key properties.
• (without a stylesheet) using colors, images and properties to map internal Firefox CSS variables, such as --arrowpanel-dimmed to new theme key properties. This option limits experimentation to UI components that are associated with a inbuilt CSS variable.

To discover the internal IDs for Firefox UI elements or internal Firefox CSS variables use the browser toolbox.

Note: This key is only available for use in Firefox Developer Edition and Firefox Nightly channels and requires the extensions.legacy.enabled preference to be enabled.

Warning: This feature is experimental and could be subject to change.

Syntax

The theme key is an object that takes the following properties:

Examples

This example uses a stylesheet named style.css to provide the ability to define a color for the browser reload button in the themekey.

The stylesheet defines:

#reload-button {
  fill: var(--reload-button-color);
}

where #reload-button is the Firefox internal ID for the reload button and --reload-button-color is an arbitrary name.

In the manifest.json file, --reload-button-coloris then mapped to the name to be used in the theme``colorsproperty:

"theme_experiment": {
  "stylesheet": "style.css",
  "colors": {
    "reload_button": "--reload-button-color"
  }
}

Then reload_button is used in the same way as any other theme property:

"theme": {
  "colors": {
    "reload_button": "reload_button"
  }
}

This has the effect of making the reload icon orange.

(image)

This property can also be used in browser.theme.update(). images and properties work in a similar way to colors.

Looks great, thanks!

Some small nits:

• "internal IDs" should probably "internal CSS selectors" given that you can use other CSS selectors too.
• In the table, I'm not sure why themes is a code quote, I think it should just be a normal word since it's not referring to any code.

needinfo'ing Jared/Mike if they have any extra feedback.

Thanks Tim, I'll start preparing the content for MDN pending feedback from Jared and Mike.

Hi Jared/Mike, do you have any feedback on the proposed content, or can we go ahead and publish?

FYI Tim, Jered, and Mike new pages now on MDN: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/theme_experiment If you have any further comments, please let me know or edit the page directly. Thank you!