Update: I initially indicated these changes applied to beta 11, when it reality they apply to beta 12. You can test this on the currently nightlies or wait for beta 12 to try it out. The samples work on beta 11, with only one bug: if the toolbar is in large icons mode, the large icon will be used and scaled down on themes where icons are always small, like on Windows.

A couple of months ago I wrote an overview of toolbar buttons in Firefox 4, including all the CSS and image work necessary for your add-ons to work on all 3 platforms. It was met with many questions, the gist of them being why is this so convoluted when it could be really simple? So, bugs were filed and revisited, and many problems were finally solved.

Firefox 4 beta 12 will contain fixes for bug 626382 and bug 616472, both of which bring the necessary icon and styling work down to almost the bare minimum. You can test these changes on the current nightlies

First of all, if you followed the recommendations in the previous article, no changes should be required. I tested the add-on I created for that post on the latest beta on all platforms and it worked just the same. So, if you already did the compatibility work for Firefox 4 testing in earlier betas, you should be good. Now let’s get to the new, simpler way of doing this.

Assuming you want to support all 3 major platforms and your add-on adds a toolbar button, the minimum you need is a 16×16 px icon and a 24×24 px icon. The 24×24 px icon is normally only used on the default Linux theme (I tested on Ubuntu) on Large Icons mode, which is the default value for the main toolbar. For all other platforms and modes, the 16x16px icon is used, with varying margins around it on Windows. In terms of CSS, all you need is this:

#icondemo-toolbar-button {
 list-style-image: url("chrome://icondemo/skin/toolbar-large.png");
}

toolbar[iconsize="small"] #icondemo-toolbar-button {
 list-style-image: url("chrome://icondemo/skin/toolbar.png");
}

Nothing else is needed.

Now, if you want to take this one step further and be a better Mac OS X citizen, your icon will look much better if it’s monochrome. For this, I recommend using chrome manifest flags to either have completely different skins altogether, or just override the main skin with the Mac OS skin when necessary. The sample add-on in the previous article uses the former, the sample add-on in this one uses the latter.

Here’s a link to the demo add-on I adjusted for the new system. It’s simpler and smaller because of one icon and some CSS files that weren’t needed anymore.

If you’re a theme author or you want to understand the details of the new system, perhaps if you need specially-sized icons for your add-on, you should read this comment that explains the changes very well. Alfred Kayser also maintains this Mozillazine thread up to date with everything that concerns theme authors. Thank you, Alfred!

Also, special thanks to Dao and Paolo for all the hard work they put into resolving these bugs!