Your own theme workshop - for beginners

Discuss application theming and theme development.

User avatar
Posts: 6743
Joined: November 17th, 2002, 12:33 pm
Location: Princeton, NJ, USA

Post Posted November 25th, 2005, 9:54 pm

Post #1

This thread is about how to get into making themes. I hope that other themers will add to it. Since Firefox 3.0 has been released, I have updated the instructions.

This thread is about how to get started in theming Firefox 3.0 and later. It is what I wish I could have found four years ago, when I started theming.

Before we start, there is one essential tool you must have: the DOM Inspector extension. DOM stands for Document Object Model, which is the blueprint for what you see in your browser layout. Install this extension now.

OK, to start on your theme workshop:

One great thing about Firefox since 1.5 is that you can set up a theme directory (call it a workbench) where you can make a change, close the browser, and when you reopen it you can see your change immediately. What follows is how to set this up.

Let’s start by setting up a workshop. Create a directory like C:\aa-theme-workshop. This will be near the top of your directory listing. Or you can play around with other names, or make a shortcut to your workshop directory. Just make it easy to get to.

Now pick a theme you want to base your theme upon. Or just pick one you are going to explore.

If you want to base your theme on another theme, consider what size icons you want. The Firefox default theme uses 24x24-pixel icons for the large toolbar buttons, and 16x16-pixel icons for the small toolbar buttons. Other themes use larger icons. Pick one where you like the icon sizes.
Last edited by ehume on April 6th, 2009, 8:15 pm, edited 10 times in total.
Firefox: Sic transit gloria mundi.


User avatar
Posts: 6743
Joined: November 17th, 2002, 12:33 pm
Location: Princeton, NJ, USA

Post Posted November 25th, 2005, 9:55 pm

Post #2

Now we play with a theme.

First, you must understand that themes come packaged in compressed files, called jarfiles. They typically have names like thistheme-1.2.3-fx.jar. The .jar extension signifies that the file is a Java archive. They are not always compressed, but we will not be dealing with uncompressed jarfiles.

When you want to look inside a jarfile, you can use a program like 7-Zip or IZarc (up to version 3.6; version 3.8 has a bug). There are others that work also, even Windows' own file compression utility - but setting that up to open jarfiles is outside the scope of this thread. The important thing is that you set up your compression/decompression to recognize jarfiles, since it will save you much time.

When you look inside a theme's jarfile, you will either see a file called contents.rdf or chrome.manifest.

Pick a version of a theme you want to work with that has chrome.manifest, if you can. If you must pick one that has contents.rdf, use the instructions in this post. If you have a theme that has chrome.manifest, skip to the next post.

For contents.rdf themes, install the MR Tech Toolkit extension and your theme in Firefox (you will need the extension for the next step). Close and reopen the browser.

Open Tools > Add-ons > Themes. Select the theme you have chosen to work with. Right-click on it to get the context menu, and select Browse Install directory (we get this from the Local Install extension). You will now be in the installation directory of your chosen theme. Do a control-a or command-a to select all and then copy everything in the directory. Now move to a workshop directory and paste everything you copied to that directory.

The reason you have to do this is because contents.rdf themes do not come with a chrome.manifest file. You must install the theme to let Firefox generate a chrome.manifest file. It also generates the chrome directory. The original jarfile is inside the chrome directory.
Last edited by ehume on April 6th, 2009, 6:40 pm, edited 11 times in total.
Firefox: Sic transit gloria mundi.


User avatar
Posts: 6743
Joined: November 17th, 2002, 12:33 pm
Location: Princeton, NJ, USA

Post Posted November 25th, 2005, 9:56 pm

Post #3

Now is a good time for those who started with a chrome.manifest theme to unpack the jarfile. It is true that you can work entirely within the jarfile without decompressing and recompressing it; but if you want to do that you can do it later. For now, I want to keep us all working on the same structures.

Note - The theme structure we are going to discuss is a chrome.manifest theme. If the theme structure you see is not what is described in this post, it is likely to be a contents.rdf theme. If the theme you have chosen is a contents.rdf theme, go to the post above and follow those directions. If the structure of your theme does not match what is described below, go to the post above, then rejoin us here.

About compression utilities: If you have Windows as your OS, you can use Windows’ own compression utility simply by renaming the jarfile from thistheme-1.0-fx.jar to This gets old fast.

Of compression utilities, I have found that IZArc is the easiest to use. With this compression utility I can go inside a jarfile without changing its extension. I can open a file inside the jarfile and change it; when I close the file - still compressed inside the jarfile - IZArc will ask me if I want to apply the changes. I usually say yes (7-Zip also does this). The other thing - and this puts it ahead of WinRAR for me - is that I can set the default output filetype to be a jarfile, saving me some steps.

Whatever you are using, unpack (decompress) the theme’s jarfile now (if you started with a contents.rdf theme, Firefox has already done the first decompression, so you do nothing at this step).

Now, whether you started with a theme compatible with a contents.rdf theme or with a chrome.manifest theme, you should now have a working directory that looks like this:

Code: Select all
   chrome (a directory)

What Firefox does when it installs the theme is to read the install.rdf file to learn what to call the thing, what version number to give it, and whether it is compatible with that version of Firefox. It then reads the chrome manifest to learn where to find the various directories of the theme structure. The icon.png and preview.png files are graphic images (png = Portable Network Graphic) that the themes manager uses.

(An aside: The icon image should be 32 pixels tall and 32 pixels wide. If not, it will be squished or stretched to that size. As for preview.png, varying sizes work, but something around 200x150 pixels does not abuse your system.)

The chrome directory in an installation package contains just this: another jarfile. With contents.rdf themes, this is the original jarfile, from which Firefox has extracted install.rdf and the graphics files. It generates its own chrome.manifest file from a file inside the original package.

In any case, we will be working without a second layer of compression. Go inside the chrome directory and if there is a jarfile, unpack it.


Now your theme needs in ID. There are two methods. Method A is clumsy. Method B is easy and easy to use. I have gone over to Method B, and I recommend you do the same.

Theme ID, Method A (for historical purposes only):

Find a GUID generator (GUID stands for globally unique identifier). You can Google around to find one. You can go here or here for web-based GUID generators. Or you can go to Microsoft’s GUIDGen page and download their GUIDGen utility.

Theme ID, Method B (use this method):

Make up an email address. Examples are,, (the ID of an extension), etc.

Copying and pasting GUID's is harder than copying and pasting pseudo-email addresses. The pseudo-email addresses can be read and understood. Instructions for working with rdf files (something we themers must do) assume pseudo-email addresses.

Use method B.


Now we look at the install.rdf file. We will use Aeon as an example.

Inside aeon-3.3-fx.jar you will find the structure listed in the codebox above.

Inside install.rdf you will find:

Code: Select all
<?xml version="1.0"?>

<RDF xmlns=""

  <Description about="urn:mozilla:install-manifest">

    <!-- Target Application this theme can install into,
         with minimum and maximum supported versions. -->
    <!-- Front End MetaData -->
    <em:description>A cool theme with pleasant colors. NOTE: To get a dropdown history from a forward or back arrow, right click on it.</em:description>
    <em:creator>Ed Hume (</em:creator>
    <em:contributor>Based on SphereGnome, created by Ken S. Lynch.</em:contributor>
    <em:contributor>BlueSphere SVG Icons and others by Vadim Plessky,</em:contributor>
    <em:contributor>Additional Tombats font icons by Tom Murphy,</em:contributor>

    <!-- Front End Integration Hooks (used by Theme Manager)-->


The <em>{ded0fc70-7215-4802-afeb-b2982d3e7225}</em> line refers to the ID of the theme, in this case a GUID. I made this ID before I learned about email-style ID's.

The <em>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em> line refers to the GUID of Firefox.

You can see the version of the theme, and the minimum and maximum versions of Firefox with which this theme is compatible.

You can also see the official “name” of the theme. This name can have spaces and apostrophes, but don’t use apostrophes: when I used an apostrophe in the “Hallowe’en” theme, Mozilla Update choked on it at the oddest times. I had to rename it “Halloween”. Other names that work are HiVis Big (notice there is a space in the name) and SphereGnome_Big.

Note that the “internal name” should not have spaces or any characters except letters, numbers, hyphens and underlines. Thus HiVis Big becomes HiVisBig, etc.

You can see where I have given credit to the originator of the theme and the original sources of the art used in the theme. Of course, I made some icons myself, but anyone looking at the originals would be able to tell where I made new ones.

For your work-in-progress, make up a new name (for example My Theme) and put it in the install.rdf file in place of the original theme’s name. Then make a compatible character string for the internal name (for example MyTheme).

Using whichever method you choose, make an ID and paste it into install.rdf in place of the theme’s ID. Do not touch the targetApplication GUID, or your theme will not work on Firefox.

Now for chrome.manifest. Here is chrome.manifest from Aeon 3.3:

Code: Select all
skin global       Aeon chrome/global/
skin mozapps      Aeon chrome/mozapps/
skin browser      Aeon chrome/browser/
skin help         Aeon chrome/help/
skin communicator Aeon chrome/communicator/

The first column tells Firefox this relates to a theme. The second column refers to the internal directories of the theme. The global, help, mozapps and browser directories are default directories from Firefox. The communicator directory is a fossil that supposedly does not need to be there. But once I took it out and my theme didn’t work. OTOH, that was long ago. Perhaps now I’ll try bundling up a theme without it and see how it goes.

The third column refers to the internal name of the theme. Get this right or you get “interesting” results when you install your theme.

The fourth column tells Firefox where to find the various internal directories.

Here, chrome.manifest is telling Firefox is that all of the directories will be found inside the chrome directory. I used to have a compressed jarfile called chrome.jar inside the chrome directory. It is unnecessary, and provides opportunity for error. Don't do it.

So go into the chrome.manifest file of the theme you have chosen and replace its internal name (e.g. - ThisTheme) with your own (e.g. - MyTheme).

Congratulations. You have just made a potentially installable theme.

In fact, let’s test it. I have an ulterior motive here - actually, two ulterior motives - so do this.
Last edited by ehume on April 6th, 2009, 8:20 pm, edited 21 times in total.
Firefox: Sic transit gloria mundi.


User avatar
Posts: 6743
Joined: November 17th, 2002, 12:33 pm
Location: Princeton, NJ, USA

Post Posted November 25th, 2005, 9:56 pm

Post #4

You are now inside your workshop directory. Make a new folder and name it something like mytheme-0.0-fx.

Now collect everything else in the directory and put it inside mytheme-0.0-fx. Then go inside it.

Inside the mytheme-0.0-fx directory you should have: install.rdf, chrome.manifest, up to two png files, and a chrome directory which contains subdirectories.

Select everything inside the mytheme-0.0-fx directory, and right-click to bring up your context menu. If you are using IZArc, select the IZArc menuitem. Depending on how you have set up IZarc, you will then see a submenu which leads you to choices, or a menuitem that says “Add to” or “Add to mytheme-0.0-fx.jar”. If you have set IZArc up to put out jarfiles as a default, you will see a menuitem that says “Add to mytheme-0.0-fx.jar”. Select that.

If you are using another compression utility, follow the method for that utility. If you are using the built-in Windows compression utility, select the option that automatically adds the selected objects (everything inside the directory) to, then rename the resulting file to mytheme-0.0-fx.jar.

Why do it this way? Because if you were inside your workshop directory and merely selected the mytheme-0.0-fx directory, you would get a jarfile with a mytheme-0.0-fx directory inside it - in essence another layer of directory structure. Since Firefox is not expecting this additional directory layer, such a theme would not install (trust me on that; it was one of my earliest mistakes). Teaching you how to properly use a compression utility was my first ulterior motive in getting you to do this test run.

Now for the smoke test. Go to the Tools dropdown menu and select Themes. This will open the Themes Manager window. Drag your new theme to the left pane of the Themes manager window. Close Firefox and reopen.

Why do I call this a smoke test? Well, the term derives from when people hand-build electrical or electronic devices. The smoke test came when you plugged it into the wall and turned it on. If nothing smoked, burned popped, etc., then it passed the smoke test.

If it fails the smoke test, close the browser (you may have to force it with ctrl-alt-del or the equivalent).

The most common failures I have run into are:

The second column of the chrome.manifest file is not exactly the same as the internal name in the install.rdf file.

Too many directory layers inside the jarfile.

Remember that we have made no changes in the theme itself. We’ve just changed the name and maybe the architecture. Better to deal with this frustrating business now and not after you’ve sweated over all your theme changes. Go back and muck around until your new theme passes the smoke test. Then move to the next post.
Last edited by ehume on April 6th, 2009, 8:24 pm, edited 7 times in total.
Firefox: Sic transit gloria mundi.


User avatar
Posts: 6743
Joined: November 17th, 2002, 12:33 pm
Location: Princeton, NJ, USA

Post Posted November 25th, 2005, 9:57 pm

Post #5

Now we are ready to set up your workbench.

You know what the ID of your theme is. Go into your profiles directory. In Windows XP is it here:

Code: Select all
 C:\Documents and Settings\[username]\Application Data\Mozilla\Firefox\Profiles

Locate the profile you are going to use. As an example, one of mine is named "vbrf3qlv.Default User". Go inside your profile. You will find a number of directories. Themes and extensions are located inside the extensions directory.

Go into the extensions directory of your profile. You will find some subdirectories. They have GUID’s as names, and represent both themes and extensions.

Find the subdirectory with your new theme’s ID. Create a shortcut to it and drop the shortcut into your workshop directory. Now when you go into your workshop you have a shortcut that leads you into your theme’s working directory, what I call your workbench.

----------------- Begin comment

This shortcut leads from your workshop to your workbench. You enter the workbench (your theme's extension directory) from your workshop through the shortcut. You get out by using your back button. Think of the shortcut as a side entrance to your theme's extension directory.

For each of my eleven themes I have two workbenches - one each for the current release of Firefox (the branch) and one for the current developmental build (the trunk).

So, I have 22 workbenches in my theme workshop. And here is where the workshop concept becomes so powerful: the branch and trunk builds use different profiles. The shortcuts from my workshops give me access to all of the themes in two profiles from one place (my workshop).

And think about this: at one point there were three lines of development in Firefox: 1.5, 2.0 and 3.0. I had profiles for each build, so I had three shortcuts for each of 15 themes. I could not have managed them all without a workshop.

------------------- End Comment

When Firefox can start and restart while using your theme with no hiccups, you have a functioning workbench. Try swapping in some new icons for the old theme’s icons so you get the hang of it.

Each change you make will show up the next time you start Firefox. Your workbench will speed up your development enormously.

What will also help you is the MR Tech Local Install Extension. It will supply you with a Restart button you can put on your toolbar.
Last edited by ehume on April 6th, 2009, 8:27 pm, edited 20 times in total.
Firefox: Sic transit gloria mundi.


User avatar
Posts: 6743
Joined: November 17th, 2002, 12:33 pm
Location: Princeton, NJ, USA

Post Posted November 25th, 2005, 9:58 pm

Post #6

A few caveats:

If you are not basing the structure of your theme on the Firefox default, it is polite to ask the author of the theme for permission. I am granting you permission now to use the structures and code in my themes.

In order to learn how to make themes, you need to learn to manipulate css (cascading file sheet language).

Resources include:

First and foremost:

Firefox Chrome Explorer
by "mcdavis941". He will teach you how to code themes!

Also:'s Creating a Skin for firefox
W3 Schools CSS tutorial
Tizag CSS tutorial
XUL at the Mozilla Development Center

Especially the box model:

Brain Jar
a 3-D box model by Hicks Design

and a bit on Mozilla-specific commands.

Finally, the Mozillazine KnowledgeBase on themes. This will teach you the whys and wherefores of themes. Study this and you will begin to see what you can do with the theme workshop and workbench you have just created.

Oh, yes: I find this tool to be indispensable: ExamDiff Pro, a directory-comparing tool. It cost me money, but there is a free version. There is other directory and file comparison software out there. I think you will find that such a tool will help you a lot.

OK, that's a start. I'm done with this series. Please feel free to post comments and tips.
Last edited by ehume on April 6th, 2009, 7:51 pm, edited 8 times in total.
Firefox: Sic transit gloria mundi.


User avatar
Posts: 1187
Joined: March 17th, 2004, 12:24 am

Post Posted November 26th, 2005, 12:08 am

Great job, ehume! Very useful information. Thanks for doing this.
"Linux is for those who hate Windows, BSD is for those who love Unix." -Some Guy
Try my themes: QuBranch and QuTrunk
Fix Firefox's Resized image scrolling speed: <b>Bug 163975</b>

Uncle Spellbinder

User avatar
Posts: 3519
Joined: May 28th, 2004, 4:52 pm
Location: Highland, IN - U.S.A.

Post Posted November 26th, 2005, 9:18 am

I know I'm not the only Firefox user who wants to know how to create a theme. Lots of info above to digest. Could a Moderator make this thread STICKY please?
My Firefox Add-Ons Collection: Firefox Essentials


User avatar
Posts: 39
Joined: January 10th, 2004, 12:05 pm
Location: Ontario, Canada

Post Posted November 26th, 2005, 5:32 pm


User avatar
Posts: 1854
Joined: January 19th, 2004, 12:19 am
Location: Northeast USA

Post Posted November 27th, 2005, 8:38 pm

There can't be too many references for theme packaging. Good job, Ed. I vote also to make this a sticky, especially since so many folks visit this forum precisely for these instructions.
Still passionate for Mozilla themes and extensions, just not actively developing them for public release anymore.


User avatar
Posts: 13671
Joined: February 13th, 2004, 5:49 am
Location: London, UK

Post Posted November 27th, 2005, 9:20 pm



User avatar
Posts: 69
Joined: February 17th, 2004, 7:30 am
Location: Maple Heights, Ohio

Post Posted November 28th, 2005, 11:16 am

This is super information, but all I want to do is tweak the size of a few (5) themed icons. Is there an EASIER way to do this ? I have tweaked the favicons I needed to and this worked well, but the actual THEME ICONS are still a mystery to me. It looks that if I could shrink the icons a few pixels, it would also make the toolbar a bit thinner..... maybe.... because if I take the icons OFF the toolbar its thinner.... would I need the author's permission to do this...even if its for private use only ??? I would post an image if I could figure out how... LOL Sorry If this should have been a new thread or posted somewhere else.
".......and the worms ate into his brain..."


User avatar
Posts: 6743
Joined: November 17th, 2002, 12:33 pm
Location: Princeton, NJ, USA

Post Posted November 28th, 2005, 8:45 pm

I suspect that for private use, you can modify a theme to your heart's content.

button icons are controlled by two main files : browser/browser.css and global/toolbarbutton.css.

How do I know this? I use the DOM Inspector.

There are two ways to use DOMi. first is to select Tools > DOM Inspector. Once the DOMi window is open, go to the File menu and select the file that is not DOM Inspector. Then click on the Inspect button at the right of the window. Now click on the magnifying glass icon on the left of the window, and click on the item you wish to know about.

Or - Install the InspectorWidget extension, and put the Inspector icon on a toolbar. Click on the button, then click on the item you want to inspect. DOMi will open automatically, showing you the code for the item you clicked on.

For whichever method you choose, go to the top of the right pane of the window. There is a list-box button on the left of the top of the right wiondow. Click on it and select Object - CSS Style Rules. This window tells you where to find the rules that control the object in question.

More about the DOM Inspector can be found here.

Now, what to do about the height of the toolbars, which is your reall interest: check out the margins of the toolbar buttons. Use the css box model code to give the buttons zero top and bottom margins.

Why margins? For that, you need to understand the box model. The best instructional image is here.

By playing with things like margin, padding and height, you might not have to touch those icon images.
Firefox: Sic transit gloria mundi.


User avatar
Posts: 69
Joined: February 17th, 2004, 7:30 am
Location: Maple Heights, Ohio

Post Posted November 28th, 2005, 9:28 pm

Thank you... I have lots to play with tomorrow, when hopefully my brain is not so tired. :-)
".......and the worms ate into his brain..."

Posts: 4
Joined: July 8th, 2004, 1:24 pm

Post Posted December 8th, 2005, 9:48 am

I tried to follow these instructions, but there were just too many inconsistencies between what was described and what was on my system to be able to do anything. Did the author of this tutorial use Linux instead of Windows? Entire directory structures seem to be different.

As an example, it says that upon entering the Firefox profile folder (C:\Documents and Settings\[username]\Application Data\Mozilla\Firefox\Profiles) we will find subdirectories with GUIDs as names. Not so on my system (Firefox 1.5 on Windows XP). What I find there is a folder called "default.dnj", and upon entering it, there are numerous other folders (most named after my installed extensions) and a large collection of files (many with .rdf extensions), and the closest to what was described (subdirectories with GUIDs as names) are only in the "extensions" folder, and there is no corresponding folder for themes that I could find.

Also, I've tried downloading two seperate themes marked for version 1.5 and above to tinker with, and neither of them look at all like described (within the jar file). There is no "chrome.manifest", nor is there a "chrome" directory, nor is there yet another .jar file within it (as described). They both, however, contained these directories: browser, communicator, global, help, mozapps, reporter.

What is going on?

Return to Theme Development

Who is online

Users browsing this forum: No registered users and 2 guests