Dark Theme Darkening: Better Theming for Firefox Quantum

The Team

Project Dark Theme Darkening was part of Michigan State University’s Computer Science capstone experience. Twenty-four groups of five students were each assigned an industry sponsor based on preference and skill set. We had the privilege of working with Mozilla on Firefox Quantum’s Theming API. Our project increases a user’s ability to customize the appearance of the Firefox browser.

(left to right)
Vivek Dhingra: MSU Student Contributor
Zhengyi Lian: MSU Student Contributor
Connor Masani: MSU Student Contributor
Dylan Stokes: MSU Student Contributor
Bogdan Pozderca: MSU Student Contributor

Jared Wein: Mozilla Staff
Mike Conley: Mozilla Staff
Tim Nguyen: Volunteer Contributor

The Project

Our goal was to expand upon the existing “lightweight” Theming API in Quantum to allow for more areas of customization. Themes had the ability to alter the appearance of the default toolbars, but did not have the ability to style menus, or customize auto-complete popups. Our team also worked on adding a more fluid transition when dynamic themes changed to allow for a smoother user experience.

Project Video

This video showcases a majority of the improvements we added to the Theming API and gives a good explanation of what our project was about. Enjoy — and then read on for the rest of the details:


Prior to this project, none of us had experience with Firefox development. After downloading the mozilla-central repository and exploring through the 40+ million lines of source, it was a bit daunting for all of us. Our mentors: Jared, Mike, Tim, and the Mozilla community on IRC all helped us through squashing our first bug.

Through the project, we learned to ask questions sooner rather than later. Being programmers, we were stubborn and wanted to figure out our issues ourselves but could have solved them a lot faster if we just simply asked in the Mozilla IRC. Everyone on there is extremely helpful and friendly!

All code written was in JavaScript and CSS. It was neat to see that the UI of Firefox is made in much the same way as other web pages. We got a great introduction to Mercurial by the end of the project and used some sweet tools to help our development process such as searchfox.org for indexed searching of mozilla-central, and janitor for web-based development.

Auto-complete Popups

We added the ability to customize the URL auto-complete popups. With this addition, we had to take in account the text color of the ac-url and ac-action tips associated with each result. For example, if the background of the auto-complete popup was dark, the text color of the tips are set to a light color so they can be seen.

We did this by calculating the luminance and comparing it to a threshold. The lwthemetextcolor attribute is set to either dark or bright based on this luminance threshold:

["--lwt-text-color", {
     lwtProperty: "textcolor",
     processColor(rgbaChannels, element) {
          if (!rgbaChannels) {
               return null;
          const {r, g, b, a} = rgbaChannels;
          const luminance = 0.2125 * r + 0.7154 * g + 0.0721 * b;
          element.setAttribute("lwthemetextcolor", luminance <= 110 ? "dark" : "bright");
          element.setAttribute("lwtheme", "true");
          return `rgba(${r}, ${g}, ${b}, ${a})` || "black";

The top image shows the auto-complete popup with the native default theme while the bottom image shows the auto-complete popup with the Dark theme enabled. Notice that the ac-action (“Switch To Tab”) text color and ac-url are changed so they can be more easily seen on the Dark background.

Theme Properties Added

We added many new theme properties that developers like you can use to customize more of the browser. These properties include:

  • icons – The color of toolbar icons.
  • icons_attention – The color of toolbar icons in attention state such as the starred bookmark icon or finished download icon.
  • frame_inactive – color of the accent color when the window is not in the foreground
  • tab_loading – The color of the tab loading indicator and the tab loading burst.
  • tab_selected – The background color of the selected tab.
  • popup – The background color of popups (such as the url bar dropdown and the arrow panels).
  • popup_text – The text color of popups.
  • popup_border – The border color of popups.
  • popup_highlight – The background color of items highlighted using the keyboard inside popups (such as the selected URL bar dropdown item)
  • popup_highlight_text – The text color of items highlighted using the keyboard inside popups.
  • toolbar_field_focus – The focused background color for fields in the toolbar, such as the URL bar.
  • toolbar_field_text_focus – The color of text in focused fields in the toolbar, such as the URL bar.
  • toolbar_field_border_focus – The focused border color for fields in the toolbar.
  • button_background_active – The color of the background of the pressed toolbar buttons.
  • button_background_hover – The color of the background of the toolbar buttons on hover.

The toolbar_field, and toolbar_field_border properties now apply to the “Find” toolbar.
Additionally, these new properties now apply to the the native Dark theme.

colors: {
    accentcolor: 'black',
    textcolor: 'white',
    toolbar: 'rgb(32,11,50)',
    toolbar_text: 'white',
    popup: "rgb(32,11,50)",
    popup_border: "rgb(32,11,50)",
    popup_text: "#FFFFFF",
    popup_highlight: "rgb(55,36,71)",
    icons: "white",
    icons_attention: "rgb(255,0,255)",
    frame_inactive: "rgb(32,11,50)",
    tab_loading: "#0000FF",
    tab_selected: "rgb(32,11,50)",

Above shows an example of some of the added properties being set in a theme manifest file and what it looks like in the browser below:


Our team learned a lot about web browser development over the semester of our project, and we had the opportunity to write and ship real production-level code. All of the code we wrote shipped with the recent releases of Firefox Quantum 60 and 61 and will impact millions of users, which is an awesome feeling. We want to thank everyone at Mozilla and the Mozilla community for giving us this opportunity and mentoring us through the process. We are looking forward to seeing what developers and Firefox enthusiasts create using the improved Theming API!

About Dylan Stokes

More articles by Dylan Stokes…


  1. dos

    Thanks guys! It maybe isn’t the biggest technological breakthrough ever for Firefox, but it’s a huge quality of life improvement for all of us dark theme users. Cheers! :)

    July 3rd, 2018 at 08:17

  2. Johan

    I’m on v62 now, and the sidebar is still not themed. Is this planned?
    (I tweaked some stuff myself using userChrome.css, but don’t know how to style the sidebar content)

    July 3rd, 2018 at 08:37

  3. qqqqqq

    While I appreciate the work done on theming. It’s really the Android version that I would like to see this on the most. E.g. when switching tabs it flashes white (grey in incognito) and there is no way to change it. Not nice when trying to read at night.

    July 3rd, 2018 at 10:36

  4. JP

    Great article! May I ask how you get the theme with the features in the video “Dark Theme Darkening” they were working on? Is it just using firefox dark theme that comes pre-installed with the most recent version of quantum, or does this team have a specific theme that can be downloaded? I’ve tried the pre-installed “Dark Theme” in firefox, but it doesn’t quite seem to match what they have in the video (e.g., the purple accents, some of the animations, etc).

    Thanks in advance for any help :).

    July 3rd, 2018 at 11:01

    1. Dylan Stokes

      The theme that was used in the video was a custom theme that one of us made. I don’t believe it was ever uploaded but perhaps we could finish it and upload it as an example. In the mean time, above there is a snippet of our manifest file that you are welcome to use as a starting point to re-create the “purple” theme in the video and expand upon it!

      July 7th, 2018 at 07:06

  5. sergio

    But new blank page and settings are still white!

    July 3rd, 2018 at 14:42

  6. James Walker

    Thank you, I really appreciate the darker dark theme!

    July 4th, 2018 at 00:42

  7. Wallace Silva

    Much better. I love it. UX Love.

    July 4th, 2018 at 05:40

  8. Trecko

    Dark 4 life! Awesome work, guys. This has really improved the Firefox experience for me personally.

    I don’t mean to criticize, because I truly appreciate the work you’ve done here, and this is definitely a huge step towards complete Firefox theming, but a couple of things—admittedly of less importance than what was fixed here—are not inheriting the theme’s color: pages like about:preferences and about:addons, the Library window (the window that appears when you click “Show All Downloads,” for example), and the web developer tools (ctrl+shift+I or F12).

    Again, I highly appreciate the work you put in already, and I don’t mean to detract from it. The functionality you provided us with is already far beyond anything else we have currently. Thank you!

    July 4th, 2018 at 12:09

    1. Dylan Stokes

      Yes, so our team essentially created a library that will be later expanded upon in the future that will setup for the other pages such as about:preferences, about:addons, etc. The in-content page was themed using a different way until our library is implemented. There is a lot that can still be done with themeing but unfortunately time was a factor for us having only a semester to complete as much as possible.

      July 7th, 2018 at 07:11

  9. Stiffux

    Great job ! I noticed change quickly after Firefox update.
    There is still a menu not themed :
    – The bookmark toolbar when it is complete add arrows icon “show more bookmarks” this menu is not themed.

    Thanks guys.

    July 5th, 2018 at 00:59

  10. Tim

    I juist want to add my voice to the previous comments: Thanks for the hard work, I love The Dark! :-) I also have the same questions JP posed. Btw, you guys are so lucky! When I was in school, there wasn’t even HTTP, much less cool browser themes and projects like this to gain invaluable experience. I also had to walk five miles to school in the snow. Ah, but I digress…

    July 5th, 2018 at 07:43

  11. Tim

    Having clicked through to your University link above, I found the answer to my (our) question: “The default Dark Theme is updated to reflect the new additions.” Reading, it’s my super power. Thanks again.

    July 5th, 2018 at 07:47

  12. Bla bla

    What about the scroll bar?

    July 5th, 2018 at 08:48

Comments are closed for this article.