The Future of Firefox Theming - Engineering Plan

(Re-)structuring Firefox theme extensions


This document provides a framework to guide the project to extend theming options present in Firefox today with a single, canonical and more capable alternative, based on WebExtensions.

You can find a comprehensive overview and our motivation from a product perspective in the Product Requirements Document (PRD). You can find information on how themes will be implemented on (AMO) in the AMO PRD.

To meet the goals as provided by the PRD, as linked above, we’ll implement the current set of epics, in order:

Each epic can be broken down into various user stories, which is covered by the remainder of this document. In Bugzilla terms, ‘epic’ should be read as ‘meta bug’ and ‘user story’ should be read as ‘bug’. During the implementation phase, engineers will break down the epics and/ or user stories into different new bugs to organize their work properly, according to the following definition of complete:

Definition of complete

“We consider the implementation of a user story as complete when it is

  1. Code complete, sprinkled with good documentation,
  2. Covered by (unit-)tests for at least a hundred percent,
  3. Covered by performance tests, if applicable, and
  4. Covered by telemetry in a meaningful way.”


Before we can ship code to our users, various quality criteria must be met. Krupa Raj will lead a team to perform the Quality Engineering tasks. These will include manually testing the user stories and regression fixes once they’re resolved and full (manual) integration tests following test documentation.

Additional (linting-)rules and coding styles will be inherited from the WebExtensions component.


We will make sure to keep the following performance requirements in check whilst implementing each epic:

Joel Maher has agreed to help us create Talos tests if we’d need that at all; newly created tests can be checked into the tree and we can take a look at the sessionstore test that Yoric created to see how to sideload an extension and other advanced harness features.

Newly created tests do need to be added to treeherder manually and Joel has agreed to assist with that.

Privacy & security

Other than the security characteristics we’ll inherit from the WebExtensions framework, we need to make sure that any property value that goes into a ‘url()’ CSS declaration is not reaching out of its sandbox of the extension package. Only local resources will be allowed.

Themes will not be allowed to define and run background scripts; only regular WebExtensions will be able to programmatically manipulate the active theme using a dedicated API.

New telemetry probes must be reviewed by a Data Collection peer, whose requirements we must fulfill to ensure user privacy.

Measure for success

We intend to use the built-in Telemetry service to measure where, how and which themes are used within the browser. A (non-conclusive) list of probes we deem useful, preferably opt-out:

We will add whether a theme was enabled and which theme was enabled at the time of a crash to crash reports.

We will add a list of installed themes and the name/ ID of the currently enabled theme to about:support.


Initial team composition: A UX lead, a product manager, a project manager, two senior engineers and a junior engineer. Additional support will be provided on a per-need basis by other engineers, addons team (e.g. product and planning) and AMO team (e.g. reviews and community).

The bulk of the engineering work is necessary for building the framework and extending LWT, for which the team will reserve a full quarter to complete. It is possible to add a team member after the framework has been put in place to work on other API areas in parallel, thus speeding up the development process.

Other epics will be picked up during the course of the quarter, each of which can and will be assigned to a single engineer. It is not necessary for all engineering members need to work on the framework or Extend LWT milestones together; parallel tracks are possible, but must be coordinated.

Code reviewing responsibilities can and will be shared amongst team members.

A second quarter should be reserved for the remainder of implementation work for epics that have been assigned a P1 status in the PRD and follow-up work in the following categories: QE testing results, performance.

Implement framework

This framework is the code that is needed as a base to be able to implement all of the epics listed below. It will require at least the following user stories:

"manifest_version": 2,

  "name": "Crazy Theme",

  "description": "I’m going slightly mad...",

  "version": "1.3",

  "applications": {

    "gecko": {

      "id": "",

      "strict_min_version": "57.0",

      "strict_max_version": "65.*"



  "icons": {

    "48": "icon.png",

    "96": "icon@2x.png"

"theme": {
"colors": {

      "accentcolor": "#d92215",

      "textcolor": "rgb(224, 41, 29)",
 "background_tab": [255, 255, 255, 0.6],
"background_tab_inactive": [255, 255, 255, 0.2]
"images": {
"theme_frame": "sample.jpeg"
"properties": {
"square_tabs": true

        Listing 1: manifest.json


  colors: {

    background_tab: [255, 170, 255]



Listing 2: background_script.js

This feature will be complete when the following user stories are implemented:

Example uses of this API would be a background script which fetches data from and shows specific background images that fit the current weather type, or a background script checks the time of year and shows specific background images that fit the current meteorological season.

Important: themes will not be able to define and run background scripts, as specified by the previous user story bullet.

Extend Lightweight Themes

In order to eventually upgrade LWT with this new Theming API, we’ll need to implement a number of user stories whilst making sure that we 1) keep existing themes available and installable from AMO on newer and older versions of the browser and 2) provide a seamless experience for users who currently have a LWT installed and upgrade to the browser version that will support WebExtension Themes.

Accessibility features

In order to make the browser UI more accessible, we’ll provide theme authors with the ability to enlarge or shrink the chrome UI only, resulting in the following user story:

Google Chrome theme parity

Parity here means that we support at least the same set of theme manifest properties that Google Chrome supports internally. This includes legacy theme properties that Chrome still supports. Properties that don’t have a canonical equivalent in Firefox will be supported as dummies; they’re there, but don’t apply any styling change. Once parity is reached, many of the requested features from the PRD will be implemented. Therefore, this is a good milestone for engineering to aim for.

It’s possible to reach absolute/ full support for Google Chrome Themes, noting the following caveats:

We’re free to support additional CSS color strings as property value, like ‘#f00’, ‘hsla(170, 65%, 40%, .25)’, etc.

The format of a Chrome Theme is a static manifest packaged together with static visual assets, fully compatible with the WebExtension manifest format, which will ease conversion of existing themes considerably.

Users will not be able to install a theme from the Chrome Store directly in Firefox, because we don’t support its package format. This also means that all a theme author needs to do in order to make the themes they created for Google Chrome available to Firefox users is zip the uncompressed theme and submit it to AMO.

Custom Icons

Replacing the current icon set with custom glyphs is not possible in any other browser currently available through a standardized API, thus a unique feature once the following user stories have been implemented:

Note that the successful implementation of this feature is at risk, because the performance of using SVG icons is not guaranteed to be optimal. There is work underway to optimize this throughout the browser, eventually switching all icons in the default browser theme to using SVG glyphs, but it is unknown at this time if that’s finished before we start work here.

Theming in-content about: pages

This epic has much overlap with ‘Google Chrome theme parity’ above, because it already allows users to customize much of their New Tab Page (NTP). However, for functional support, the following user stories will be implemented:

We have demonstrated in one of our experiments that it’s feasible to use realtime, playing videos as their background, instead of plain images. This feature is also demonstrated by the Opera browser and seems like a fun, whimsy thing to support. However, playing a video in the background is rather CPU intensive and may downgrade browser performance. This added complexity means that this feature is out of scope for our first milestone and will be considered for a future milestone.

Note: We’ll need to make sure videos are only playing when the about: page is in view.


We can’t assume our API is complete, covering all possible use-cases and satisfying the needs of each user. Theme authors may want to propose one or more different properties that may be used to style parts of the browser that can not be styled with the current set of APIs available, resulting in the following user stories:


  "manifest_version": 2,

  "name": "Moar Custom Icons",

  "description": "Example of a theme experiment",

  "version": "1.0",

  "applications": {

    "gecko": {

      "id": "",

      "strict_min_version": "57.0",

      "strict_max_version": "65.*"



  "icons": {

    "48": "icon.png",

    "96": "icon@2x.png"


  "theme": {

    "icons": {

      "back": "custom-back.svg",

      "forward": "custom-forward.svg",


    "experimental": {

      "icons": {

        "overflow_arrow": [{

          "selector": "#overflow-button",

          "properties": {

            "list-style-image": "custom-overflow.svg",

            "-moz-image-region": "rect(0, 18px, 18px, 0)"


        }, {

          "selector": "#overflow-button > .toolbarbutton-icon",

          "properties": {

            "margin": "3px 2px"







Listing 3: manifest.json

Appendix A - Community survey results

During the course of September 2016 Jared Wein and Mike de Boer ran a survey across multiple relevant Mozilla communication channels, asking members the question ‘What if you could re-invent Firefox Theming?

The amount of responses totalled 352, which exceeded our expectations, and we were able to draw the following story based on the results that we analyzed:

Have you made a lightweight theme before?

21.8% yes

What do you like about lightweight themes? (48 responses)

A strong majority (70%) of lightweight theme authors said that they liked how lightweight themes were simple and easy to make. The next group, at 6%, said that they liked how lightweight themes always remain compatible after Firefox updates. 4% of users also liked that they were easy to install with no restart required. A couple people complained that they were too simple and there was too much spam in the themes section of the Add-ons website.

What do you feel was difficult to do or missing from lightweight themes?

(47 responses)

A little less than (42%) half of responses would have liked to do more than just a couple of images with lightweight themes. They would like to apply background images to other parts of the browser, change icons, buttons, and the size-of and location of browser components. The next group of responses (10%) wanted more support for scaling, repetition, animation, and position of background images. Improved documentation (8%) and a lack of a development environment such as an in-browser editor followed (6%). The last two groups of responses wanted the ability for themes to change based on external factors (2%) and separate images for the tabs and tab toolbar (2%).

Have you made a XUL theme before?

23% yes

What do you like about XUL themes?

A strong majority of the respondents agreed firmly with 71.2% that XUL themes are awesome in allowing to touch and customize all the things. The second largest group of respondents seek out XUL themes because they offer more nuts and bolts to tinker with than lightweight themes at 11.5%, while the familiarity with the CSS styling language is the main reason to like them for 7.7% of the respondents. Two other notable groups are people who like dark themes, which are apparently only really available as XUL themes, and ones who feel that XUL themes are the easiest thing to make on this planet, each at 3.9%.

What do you feel was difficult to do or missing from XUL themes?

The largest amount of responses (29.8%) said that it is a real pain to keep these themes up-to-date and working, with the current fast release cycle of Firefox and the fast pace of development. 28.1% of the respondents rightfully complained that they need to use exotic, undocumented technologies and unknown CSS selectors in order to create a working XUL

theme. Whilst 15.8% claimed there is nothing wrong with XUL themes and we should keep it as-is, another 12.3% is sad about the lack of documentation or any kind of manual to get started. Packaging and delivery of XUL themes is not considered optimal by 10.5% of respondents and that ultimately very few of these themes can be configured after installation (3.5%).

Why do you install themes?

About half (47%) of the survey responses want to personalize Firefox. These people said that they want to make Firefox "their own" and have fun showing it off. They enjoy having full control over the user interface through XUL themes and like the ability to set arbitrary CSS. The next set of responses (16%) asked for a "dark" Firefox, making it easier on the eyes at night. These responses were generally focused on the toolbars and menus of the browser being dark. At 12% of responses was closer integration with the operating system followed closely by 11% of responses saying that they felt the default theme was boring and bland. The last category of responses that received multiple votes was to allow themes to undo recent changes to the

user interface, as an attempt to keep things the same that they've been for the past months/years.

What capabilities would you like themes to have?

More than half (56%) of the survey responses want full control over the browser UI. They would like to move and hide items, change tab shapes, replace icons, context menus, scrollbars, and more. Following this large group, we had close to 5% of respondents who wanted to simply change basic colors and another group, also close to 5%, that wanted to make it easy for users to make simple tweaks to their browser or an installed theme through a built-in menu or tool. Native OS integration, such as using platform-specific icons and scrollbars, followed closely at 3%. Also at 3% of responses were requests from users who require larger icons and improved readability of the browser's user interface for improved accessibility. Not far behind, and ironically next in the order of responses, were requests for a smaller browser UI (2%). These users generally want to maximize the amount of screen space that web pages can use. Both "dark themes" and "themes not breaking with future releases" got 2% of responses. In our last group of responses at or above 1% was themes that could change based on external factors (time of day, season, month, web color, or a very slow animation), restartless and easy to trial, ability to apply multiple themes to create a "mash-up", and to lighten the tab bar.

What parts of Firefox are most important to you to be able to change the

appearance of? Why?

Almost 20% of the respondents can not make a choice between the parts of Firefox and thus want to customize the app in its entirety. Following closely with 16% is the group of respondents that think the tabs area is the most important part for themes, while half that number choose toolbars, (toolbar)button icons and the area above the tabs, including the window decoration and window controls. Interestingly, the wish to be able to theme in-content pages is as strong as that of the Awesomebar and respective navigation controls: 6.8%. Changing the colors, palette and fonts used for the UI are the other most notable choices from the community of respondents at 6.4% and 4%, respectively.

Are there theme-related features from other browser or apps that you would

like to see incorporated into Firefox?

An overwhelming majority of the respondents insist that we don't need to change a thing and that other apps don't offer grand alternatives at 36.5%, or simply can't think of any. The Vivaldi browser came up in our preliminary research and also takes a prominent position as device of inspiration for theming features at 11.2%. A dark theme like other apps already offer in their package (5.9%), applying tints of color on SVG icons and background masks (2.9%) on UI elements - most notably the title bar - and take Opera's about:newtab theming capabilities (2.4%). A notable response from 2.9% of respondents was to introduce a live theme editor in Firefox with sharing capabilities, so that theme creators can take existing themes to tweak to their own liking and (re-)share with others.


We are very very thankful to everyone who participated in the survey and the discussions that originated from this initiative. It greatly influenced our focus area and helped guide us towards formulating goals, setting the right priorities and the necessary motivation to build something truly awesome with the confidence that it will make theme authors more productive and end-users more delighted when they use Firefox every day. Thank you!

Appendix B - Prototyping phase summary

After receiving and digesting the results of the community survey, we planned and started the next phase: build prototypes, focusing on the more technically complex areas and so-called unknown unknowns.

We leased the ‘cedar’ project branch and started whipping up a theming API, based on WebExtensions, as quickly as we could in the following formation: Jared Wein, Matthew Wein and Mike de Boer.

We used a lightweight development process and tried our best to document our progress using Bugzilla. This is a summary of what we’ve learnt and built.

Prototype 1: Lightweight Themes

We started here to investigate how difficult it would be - roughly - to reach feature-parity with LWT. And what needed to be done, technically, to eventually replace them. Working on this prototype allowed us to get familiar with WebExtension API development and the inner working of the LWT manager and consumer. The toolkit part and the browser parts. The good parts as well as the bad.

Prototype 2: Custom toolbar icons

This screenshot shows off the result of our experiment to support SVG glyphs as toolbar icons, anywhere:

Listing 4: custom icons screenshot

As you can see, an emoji-themed browser is something that might not be a great fit in the real world, but we definitely learnt that using SVG for icon replacements are a great option for us. Choosing a single, ubiquitous format made our lives a lot easier and we expect for theme authors as well.

Prototype 3: UI sizing

We figured that adding the capability to scale the UI would a great feature for theme authors, but we weren’t sure whether our implementation ideas would work. Thus, we set out to make sure it did for this prototype.

We added a property to the manifest, called ‘scale’, that was allowed to have the values ‘small’, ‘normal’, ‘large’, ‘x-large’. Each of these settings would multiply the current device pixel ratio to scale accordingly.

This prototype was completed in a manner that affected the chrome UI as well as content.

Prototype 4: Developer Edition

Please see prototype 6; our experiments show it is certainly possible to convert all of the Developer Edition browser themes (dark and light variants) to be part of a WebExtension theme instead. Inserting a screenshot is not quite necessary, because, well, it looked exactly like Firefox Developer Edition!

Prototype 5: About:home and about:newtab

Please see prototype 6, where we also demonstrate the success of this prototype.

Prototype 6: Dynamic updates

In the trend of a picture says more than a thousand words, let’s try a video:

Listing 5: Extreme theme demo