Improving Themes in Firefox


Last year, we started thinking about how to improve themes in Firefox. We asked theme designers and developers for their thoughts too, and received over 250 responses. After sorting through the responses and a few months of deliberation and experimentation, we have a plan, and would like to share what we’re going to do and why.

Let’s start with the “why.”

Currently, Firefox supports two types of themes. Complete Themes and Lightweight Themes (aka LWTs, formerly “Personas”, and now just “Themes” on

Lightweight Themes are very popular. There are currently over 400,000 such themes on (AMO). They’re extremely simple to create; anyone can create one by just uploading an image to AMO. I made my first LWT eight years ago, and it still works fine today without any changes. However, LWTs are very limited in what they can do. They can lightly modify the default Firefox appearance with a background image and set a couple of colors, but nothing else. The survey confirmed that there’s a lot of interest in giving LWTs more creative control over how the browser looks. More backgrounds, colors, and icons on more UI elements.

Complete Themes, the second type of theme, completely replace the default Firefox appearance. Authors must provide all the needed CSS, images, and icons for the entire browser (from scratch!), which makes Complete Themes flexible but difficult to create and maintain. Authors have to understand Firefox’s complex and ever-changing UI internals, and there’s little documentation beyond Firefox’s source code. This leads to a serious compatibility burden, as authors need to invest time to keep their theme working with each Firefox release – only 60 of the 500 Complete Themes on AMO are compatible with current Firefox releases. Further, we’re not able to directly fix these issues without limiting our ability to improve Firefox. And since only 0.089% of Firefox users use a Complete Theme (less than 4% of the usage of LWTs), we’re going to focus on improving theming in other ways.

Firefox extensions (as opposed to themes) can also run into these problems, as there is no JavaScript API to control the appearance of the browser. Legacy add-ons wanting to do this had to directly alter the UI’s internal DOM and CSS. As with Complete Themes, this can give an extension great power, but it comes with a serious price in complexity and compatibility. WebExtensions are unable to access any UI internals, and so are particularly in need of a solution.

What we’re doing

We want to fix Firefox so theming is better for everyone.

The next generation of Firefox themes will blend LWTs’ ease of authoring with the additional capabilities we see most often used in Complete Themes. At its core is a JSON manifest, mapping defined property names to the underlying UI elements. Theme developers will be able to control a variety of styles on these properties (such as colors, icons, and background images), and Firefox will ensure the manifests are supported in a stable and well-documented way across future releases and UI updates. These themes will be layered on top of the default Firefox appearance, so you can create a trivial theme that just changes one property, or a complex theme that changes all of them.

The goal is to provide capabilities that enable people to make themes they love and use. We think it’s possible to make themes in Firefox powerful without the previous pitfalls. To get started, we’ll initially support the same properties as Chrome, to make the thousands of Chrome themes more easily available in Firefox. Then we’ll expand the set of properties in our API, so that Firefox themes will be able to do more. We expect to continue adding to this theming framework over time, with your feedback helping to guide what’s needed.

We also recognize that a property manifest won’t have all the capabilities of direct CSS manipulation, especially during the time we’re expanding coverage to cover the most common use cases. So, for theme authors who need additional capabilities (and are willing to bear the burden of supporting them), we’ll provide an “experimental” section of the manifest to continue to allow direct CSS manipulation of the Firefox UI. This is similar in spirit to WebExtension Experiments, and usage will also be restricted to pre-release versions of Firefox.

A WebExtensions API

Finally, we’re adding a WebExtensions API for theming. It will have the same capabilities as the JSON manifest’s properties, except via a JavaScript API, so add-ons can make dynamic changes at runtime. This will enable add-ons to do things like adjusting colors based on the time of day (e.g. Flux), or matching your theme with the weather outside.

Questions and Feedback

For more information on our current work, see our Engineering Plan. We’ve just started some of the foundational work, but would welcome your input as we move towards building the first version that will be usable by theme authors. Our goal is to have this in place before Firefox 57 ships in November, which will end support for Complete Themes. We currently expect early testing to begin in Nightly over the next few months.

Please address your questions and feedback to the Dev-Addons list at

We’re also keeping a list of Frequently Asked Questions, check it out to see if it answers your question.

How useful was this post?

Click on a star to rate it!

Average rating 0 / 5. Vote count: 0

No votes so far! Be the first to rate this post.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.