Add-ons fox
Categories: developers themes

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.

29 comments on “Improving Themes in Firefox”

  1. kwerboom wrote on

    I’m sad that Complete Themes are being removed and I’m sad that Legacy Add-ons are being removed. I loved the flexibility that Mozilla brought to the web with Firebird in 2003. I know there are people that are going to be angry about this. I should be angry too, but I know that Complete Themes and XUL based Legacy Add-ons were always a kludge. That kludge has been a double-edged sword first giving Firefox a marketable tool to overcome IE6/IE7 and now an anchor holding Firefox back against Google Chrome. I realize that in moving to a standard API for extensions and themes, some of the power and a lot of the magic will be lost. I also realize that it is a necessary change so that Firefox can move to multiprocessor support, proper sandboxing for security, and flexibility to change the core engine in the future as needed along with making embedding that engine like WebKit a possiblity again. Progress is a balancing act between giving something up that is loved so that new possibilities can open up. The worse thing one can do sometimes is stand in a safe place when one should have taken the risk and jumped to a place with more opportunity. I hope that what Mozilla is doing will take advantage of those opportunities to put it back on top again.

    1. RedBoo wrote on

      You don’t “catch up” by trying to copy and clone somebody else. To be a leader one must play the part and march to their own tune. These moves by mozilla will be the stakes that kill off Firefox by removing the features that made it great. Why the heck do I want to use a trashy, slow Chrome clone? Even if I was concerned about privacy Chromium is available. Customizability and freedom is their bread and butter. Removing that will only kill off the userbase and attract no one. They are taking no risks and rather making a stupid calculated decision based on market trends. If they want to take a risk, they should become a leader with their product and jump ahead, not play catch up.

  2. Ben Bucksch wrote on

    Kairo has maintained a full theme over many years, and suffered from the many cuts that this “full theme” approach bring with. This hands-on, practical experience has led him to suggest some concrete design how “non-lightweight” themes in Firefox should work:

    It is an excellent writeup. His points under “Here’s a list of things I’d like to see in the underpinnings this next-generation themes architecture:” are precisely what I would recommend doing as well. (I haven’t written any themes, but I’ve been technical lead for several commercial XUL applications.)

    Anybody who undertakes to replace themes, please use Kairo’s “underpinnings” as guideline for the design.

    1. Robert Kaiser wrote on

      FWIW, I will stop my roughly 18 years of creating themes with Firefox 57. A theme as radical in design as LCARStrek is not possible with the new scheme and doing it in a way that is less “radical” doesn’t nearly create the right look. I guess Firefox 57 and later is not ready for a 24th century look. 😉

      1. Mike de Boer wrote on

        Robert, the ideas that you mentioned in you blog post resonate with our plans, in fact: we are moving all the things to CSS variables, all icons are planned to be SVG all the way, our icons will be customizeable on a very detailed level and we are also planning to specifically style in-content documents like about:newtab and other, based on popular demand.

        Additional, we’ll add the ability to propose new APIs using a Nightly-/ DevEdition-only hook to extend the manifest with additional properties. This is very similar to how new WebExtension APIs can be prototyped and proposed today.

        I really recommend reading through the Engineering Plan[1] and please reach out to me or anyone in #teamaddons with your thoughts about what’s missing. Thanks!

  3. Son wrote on

    If I were you, I would have given priority to a dozen of remarkable Firefox-only features to differentiate from Chrome, and then get all the Chrome API, and then get back to building Firefox-only stuff.

    You’ll get a lot of bad PR if you do it the way that’s described and you don’t have noticeably larger flexibility than Chrome on Firefox 57 release day.

    1. Mike de Boer wrote on

      Well, if you insist on comparing Chrome to Firefox: we’ll be moving forward where Chrome stopped.

  4. WhereIsXUL wrote on

    Will it be possible to implement multi-row tab bar using this “next generation of Firefox themes”? This is one of the core features of Tab Mix Plus that has over 775k users.

    1. Mike de Boer wrote on

      This sounds more like a WebExtension API capability than a theme capability. Admittedly, there’s a gray area where a theme stops and a WebExtension API takes over, but here we are limiting ourselves to whatever changes the look & feel of the current UX.
      Anything that allows the (re-)ordering of UI components is out of scope for this particular project, but that does not mean it will _never_ be possible through a WebExtension API! We have a community-driven approach to adopting new APIs and proposals, so please feel free to continue to reach out or even contribute by implementing a WebExtension Experiment[1]!


  5. Arthur Lanher wrote on

    Mozilla team, I appreciate the effort in trying to hear what we want. Keep up the good work and remember that flexibility is a top priority.
    Best regards from Sweden.

  6. Nemo wrote on

    Wouldn’t it be much simpler to do like Opera, grab a copy of Blink/Chromium and add features on top of it?
    This tearing Firefox apart one piece a time is becoming agony.

  7. dbc wrote on

    Losing some of the abilities from Classic Theme Restorer will be very sad. I have my location bar, and nav bar buttons, set up like Chrome. Having to have the home button and stop/reload on the RHS of the location bar would be a deal breaker for me. I’d jump straight to Chrome.

  8. dbc wrote on

    Specifically, this is what my browser chrome looks like with the current Nightly build:


  9. David wrote on

    Over and over, it seems like Mozilla’s ideas look good from a *distance*, but show cracks and weaknesses when examined up close. And it seems like the people making the decisions are only capable of seeing this distant view, while ignoring anyone implying things don’t look so good up close.

    For example, this idea on themes sounds pretty good on its own. Give more capabilities than the so-called lightweight themes (a background image is -not- a theme), while getting away from the maintenance clusterfuck that is full themes. And by giving themes access to WebExtension functionality, you’re implying it could go the other way, too: extensions having access to theming functionality.

    By separating out the concepts of behavior and display, it’s a bit like separating structure from style in a web page (HTML vs CSS). That is, the WebExtension API surface doesn’t have to handle all the stuff that could reasonably be described as theming changes, such as (for example) what Classic Theme Restorer does. Instead, all of that is built into the ‘Theme’ API, while allowing Themes and WebExtensions to use each other’s API’s to handle things they themselves can’t.

    If that was where you were actually going with all these changes, the idea sounds great. However: No one has ever communicated that this is the idea of what you’re doing; No one has defined the APIs that will show that such cross-pollination can be used (despite the example with the pink theme and the animated background); No one has put down the design specs that people could review and refine; and almost every attempt to communicate with Mozilla seems to get stonewalled.

    And of course, the problems with undefined APIs is that there never seems to be any long-term commitment that anyone can rely on. And reviewing the engineering plans, it looks like a very narrowly-scoped plan, with only the very bare minimum you can get away with, rather than a design to make people interested and excited, with the idea that there’s something worth getting invested in, there. There are no goals, there are no deadlines.

    What do you envision Firefox as being, 5 years from now? Because from everything coming out of Mozilla, there’s no much vision at all. It feels like old Netscape. It feels like the W3C before the WHATWG lit a fire under their ass about HTML. It feels like Mozilla, and particularly Firefox, has no future.

    1. Mike de Boer wrote on

      Apart from the fact that Mozilla was/ is one of the driving forces behind the WHATWG, I hope I can alleviate your concerns a little bit by pointing you at the meta-bug[1] that encapsulated the implementation work that also shows what is in-progress right now and what will be done in the (near) future and also to the most important code locations[2][3][4] you can inspect to get a feel what things look like currently.

      [2] The API handler module:
      [3] The schema definition:
      [4] The unit tests show off all the features as currently implemented:

  10. Donna wrote on

    I like Firefox the way it is and if I wanted Chrome “like” I would probably use Chrome. Why not keep the lightweight themes that everyone seems to love? Not everyone likes a change if it really does not improve their life in anyway.

    1. Jorge Villalobos wrote on

      Lightweight themes will continue to work as they did before. Designers will have additional capabilities, but it’s entirely their choice if they want to use them or not.

  11. DanielGrey wrote on

    As ex-Firefox user who left when Chrome was released I have to say I love what Mozilla is finally doing with Firefox: removing bloated features like ui customization and bloated theme features, replacing the way too complex and slow xul extensions system with webextensions, removing the ugly outdated UI in favour of a state of the art one with Australis!

    But: Why should I switch away from Google Chrome when it offers the same? The browser market lives from diversity and not from senseless make-it-all-look-like-another-product – which is done today by almost every Chrome competitor to get a slice of the pie too. People use Firefox because it is customizable, people use Chrome because of simplicity, design and minimalism.

    Mimicking Chrome is a bad idea. I rather would switch to Brave before I would install Firefox! Why? They, unlike Mozilla, are actually trying to bring in creativity into – as more skilled users would say – a boring product.

    For example an upgrade of standard tab browsing, a fully non-native ui, many security based features and this is only scratching the surface of what is planned for Brave. Also, in Mozillas attempt to be a more attractive Chrome similar browser (without Blink) they are willingly sacrificing their users features and options just to reach this goal.

    We say Google are evil but at least they never would do that to their user-base: ignoring their interests in favour of others. As long as Mozilla tries only to be a follower instead of a leader they never will be a serious competitor towards Chrome.

    Actually sad that an ex-Firefox and simple user is able to realize that instead of Mozilla.

    No Mozilla, most Chrome users will not use Firefox, even with all that changes you made to be of interest for us.

  12. Frank Lion wrote on

    ‘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….’

    For completeness and posterity, perhaps I should just point out that in 2010 that 7% of Firefox users used Complete Themes and 2% used LWTs –

    Back in 2007, the Complete Theme usage was even higher, with top themes each being downloaded at the rate of 200,000 – 400,000 a week…until that magically changed overnight – and much more followed.

    Quite how this steady decline in Complete Theme usage happened is a tale best left to Mozilla to explain or not, being the key perps.

    Bet this one doesn’t get published. 🙂

    1. Mike de Boer wrote on

      It did get published! 🙂

      But in all seriousness, we also acknowledge the big successes we’ve had in the past with customizability that allowed savvy theme authors to change everything. But we also acknowledge the failure of the _how_ that was possible and how that bit our most engaged users in the behind whenever we needed to make changes to the browser.

      In fact, I think that the plan outlined in this blog post tells the story and makes it full-circle on Firefox 57 release day: we needed to come up with a Theming system that allows for as much customizability as possible, without the caveats that Complete Themes have. The feature set we’ll be able to get done at said release day will not be the end-goal; this is and will be an ongoing project. But we need it to start here and grow.

  13. Jesse wrote on

    I think that people who use the stable version of firefox (like myself) would be equally interested in themes that use the experimental section of the manifest. I think they might value this customizability enough to not mind the ui breaking occasionally with firefox updates. Maybe there could be a message like “this theme heavily modifies firefox’s appearance and could cause graphical glitches, continue?” when one of these themes is being installed.

  14. Terra wrote on

    Please let us theme every part of the browser 🙁

  15. A soon to be ex-Firefox user wrote on

    If nothing changes, I will stop using and recommending Firefox the moment CTR stops working with the Developer Edition; if I wanted a barely extensible browser, I would be using Safari (chrome and chromium are ruled out due to privacy concerns)

  16. carrer wrote on

    I don’t care about “colors, icons, and background images”. All I want is the ability to undo some of the “awesomeness” Mozilla has inflicted on the Firefox UI in the past few years. The current location bar dropdown is a perfect example of what I mean – a complete mess out of the box.

    Today, the tool of choice for this is userChrome.css. Please make sure to keep it around, or at least provide similar capabilities in the upcoming theming framework. Thanks.

  17. Robert Kaiser wrote on

    FWIW, if a themed look of Firefox like in is still achievable with what’s planned for this new theme architecture, please let me know. Right now I’m acting under the assumption that it’s completely impossible and prepare to end development of my theme for when 57 hits Nightly.

    1. Mike de Boer wrote on

      Please see my reply to your previous comment. Thanks!

  18. Chris Southwick wrote on

    Could you expand on the amount of customization that will be permitted? Specifically will it be possible to mimic the look of FT Deepdark with Classic Theme Restorer enabled?

    Additionally, Tab Groups and Classic Theme Restorer have notices that there will be no further development on them to be compatible with Firefox 57 and I’m afraid that without replacements – or even the possibility that replacements for them can be made – I will be forced to stop updating Firefox at version 56 or attempt to see if something like Palemoon will support these extensions.

    FT Deepdark, Classic Theme Restorer, and Tab Groups are all essential to my browsing experience and I cannot update to a version of Firefox that won’t support similar functionality.

  19. Musard wrote on

    Since Chrome and Edge, there is only one thing that Firefox does better than the competition : customization. If I still use Firefox, it’s because of the complete themes and addons I don’t find elsewhere.

    If I just wanted a simple and fast browser, with a common UI, I would already migrated to Chrome or Edge. Like many users.

    I’m afraid Firefox 57 will be just an other clone of Chrome…

  20. clintc wrote on

    I absolutely cannot stand chrome. It is too restrictive. I have been using firefox since before it was even called that. Those ‘personas’ were always garbage. I always used Complete Themes. Ever since firefox 4.x there has been a change, a change to become just another chrome clone. It has slowly been going down that path for years now.

    I doubt anyone in charge will actually read this, but if you take away everything that made firefox great (and lets be honest, they have chipped away at that for years now), then people will just turn to chrome instead.

    Why use a half baked firefox-chrome wanna-be, and just use chrome instead.