Add-ons: Complete Themes


Porting a theme over to Pale Moon or updating your theme for the next version?

If you're looking for Complete Themes that are compatible with Pale Moon

How to: Create a Complete Theme

Please note: In order to create such themes, extensive use of CSS is required. If you currently are not confident with CSS, please take time to review tutorials such as W3Schools CSS Tutorial, as well as reviewing Mozilla-specific CSS extensions, which are used extensively in themes. It would also be worth looking at the XUL Reference, to be fully aware of how particular elements are named.

Setting up the environment

As the default theme cannot be extracted from the files distributed with the browser without specialised tools, the easiest way to get started is to inspect an existing theme. A perfect candidate for this would be the Default Theme Template, which was purpose-made for new theme developers to start working on a theme. This is literally the default theme, with the additional packaging that third-party themes typically come with.

To make this theme your own, even without touching any CSS, you need to change the names and IDs used, plus the icon. There are three which you will need to adjust: install.rdf, chrome.manifest and icon.png. Let's start with install.rdf. For reference, the copy that is included in the Default Theme Template is below:

<?xml version="1.0"?>

<!-- This Source Code is subject to the terms of the Mozilla Public License
   - version 2.0 (the "License"). You can obtain a copy of the License at
   - -->

<RDF xmlns=""

  <Description about="urn:mozilla:install-manifest">
    <!-- Change your UUID here. This can either be in the id@name form 
       - or the "bracket" form. It must be unique! -->
        <em:name>Default Theme Template</em:name>
    <!-- The theme description.-->
    <em:description>The Default Theme, packaged to build your own theme for Pale Moon.</em:description>
    <!-- The theme creator - that's you! Make sure to use whichever
       - name you prefer to be known as - this could either be a 
       - username or your real name.-->
    <em:creator>Your Name Here</em:creator>
    <!-- The internal name for the theme - make this unique
       - so that nothing else will try to use it. It's important! 
       - Also make sure to use the same name in chrome.manifest. -->
    <!-- Legacy (but still probably used somewhere) flag to 
       - tell lightweight themes they can be used with this theme.
       - Note that in real world scenarios the two can't be used
       - together without use of an extension that enables it. -->



As noted in the comments in the file itself, you will need to make sure the names and IDs are changed accordingly to suit your theme. For chrome.manifest, you will note that the same name as was used for the em:internalName is used here. For example, see below:

skin    browser theme-template chrome/browser/
skin    global theme-template	chrome/global/
skin    mozapps theme-template chrome/mozapps/

skin    os theme-template chrome/os/linux/
skin    os theme-template chrome/os/darwin/ os=Darwin
skin    os theme-template chrome/os/winnt/ os=WINNT

You will need to make sure to replace "theme-template" with whichever name you set in install.rdf. The rest can stay the same.

For icon.png, this is a 64x64 icon that will be used to display your theme on both about:addons and on the Pale Moon Add-ons Site.

Understanding the CSS files

As these CSS files will, in total, style the entire browser, each serves a particular purpose, and as such not all of them need changing, depending on what you want to do with your theme. In fact, for most themes, hardly any is changed, compared to the amount of files that are available, as they serve their job well and most theme authors are reasonably content with how they are styled. As such, here's a run-down of each CSS file in the default theme:

Application styles (browser)

/browser Description /browser Description
aboutCertError.css styling for SSL error pages sanitizeDialog.css styling for the "clear recent history" window
aboutPrivateBrowsing.css styling for the private browsing information page searchbar.css search bar styling (buttons etc; main styling is in browser.css)
aboutSessionRestore.css styling for the session restore page setDesktopBackground.css styling for the "set desktop background" window
aboutSyncTabs.css styling for the synced tabs page syncCommon.css common styling for sync dialogs
autocomplete.css styling for the address bar history drop-down syncProgress.css styling for sync progress page
browser.css main browser styling (e.g. tab styles, toolbar icons, etc). syncQuota.css styling for sync quota window
engineManager.css styling for the search engine manager window syncSetup.css styling for sync setup dialog
pageInfo.css styling for the page info window
/browser/devtools Description /browser/downloads Description
common.css hook to the built-in devtools styling for any add-ons which expect it allDownloadsViewOverlay.css styling for the all downloads view in the places window
/browser/feeds Description contentAreaDownloadsView.css styling for about:downloads
subscribe.css styling for the feed subscribe page downloads.css general downloads styling, including both icons and popups for the downloads manager
subscribe-ui.css styling for the controls on the feed subscribe page
/browser/places Description /browser/newtab Description
editBookmarkOverlay.css styling for the "edit bookmark" dialog used when clicking on the bookmark button on an already-bookmarked site newTab.css styling for the new tab page
organizer.css styling for the toolbars/menus in the places window (history/bookmarks manager) /browser/permissions Description
places.css styling for the content of the places window aboutPermissions.css styling for permissions manager page (about:permissions).
/browser/preferences Description /browser/statusbar Description
applications.css styling for the applications tab in Preferences window dynamic.css styling for the progress bar in the status bar
preferences.css styling for the Preferences window overlay.css styling for controls placed in the status bar (includes the Downloads Status button, progress meter and status widgets, and Status Bar preferences button)
prefs.css styling for the status bar's preferences window

Toolkit styles (global and mozapps)

/global Description /global Description
about.css common styling for "About" pages (e.g. about:about) listbox.css common styling for listboxes
aboutCache.css styling for about:cache menu.css common styling for menus
aboutCacheEntry.css styling for entries in about:cache menulist.css common styling for menulists
aboutMemory.css styling for about:memory netError.css common styling for various error pages
aboutReader.css styling for reader view notification.css styling for notifications. (NOT including desktop notifications - see alert.css in /global/alert)
aboutSupport.css styling for about:support numberbox.css common styling for numberboxes
appPicker.css styling used for the dialog in selecting a default application passwordmgr.css styling for the password manager
arrow.css common styling for arrows popup.css styling for the notification popup
autocomplete.css common styling for autocomplete (e.g. in urlbar) preferences.css common styling for preferences windows
buttton.css common styling for buttons printPageSetup.css styling for the printer page setup dialog
checkbox.css common styling for checkboxes printPreview.css styling for the print preview dialog
colorpicker.css common styling for color pickers progressmeter.css styling for progress meters
commonDialog.css common dialog styling radio.css styling for radio buttons
config.css styling for about:config resizer.css styling for the window resizer (usually shown in windows that can be resized)
customizeToolbar.css styling for the "customize toolbar" dialog richlistbox.css common styling for richlistboxes
datetimeinputpickers.css styling for html date/time pickers scale.css common styling for sliders
datetimepicker.css common styling for xul date/time pickers scrollbars.css scrollbar styling
datetimepopup.css panel styling for html date/time picker scrollbox.css common styling for scrollboxes
dialog.css styling for dialogs spinbuttons.css common styling for spinbuttons
dropmarker.css common styling for dropmarkers splitter.css common styling for splitters
expander.css common styling for expanders tabbox.css common styling for tabboxes (groups of tabs, e.g. as seen in Preferences - Advanced)
filefield.css common styling for file select fields tabprompts.css styling for in-page alert boxes
filepicker.css common styling for file pickers textbox.css common styling for textboxes
findbar.css find bar styling toolbar.css common toolbar styling
global.css common styling for various UI elements (e.g. windows, dialogs, status bars, separators) toolbarbutton.css common toolbar button styling
groupbox.css common styling for groupboxes tree.css common tree styling
inContentUI.css common styling for "in-content pages (e.g. about:addons) wizard.css common wizard window styling (e.g. Migrator window)
linkTree.css common styling for link trees
/global/alert Description /global/console Description
alert.css styling for desktop notifications console.css styling for the toolkit error console
/global/dirListing Description /global/media Description
dirListing.css styling for directory listings TopLevelImageDocument.css styling for pages when viewing individual images
global/in-content Description TopLevelVideoDocument.css styling for pages when viewing individual videos
common.css common styling for in-content pages (used only in PM v28+) videocontrols.css styling for HTML5 native video player
info-pages.css common styling for info pages (e.g. network error) (used only in PM v28+)
/mozapps Description /mozapps/xpinstall Description
aboutNetworking.css styling for about:networking page xpinstallconfirm.css styling for the add-on install popup window
aboutProfiles.css styling for about:profiles page
aboutServiceWorkers.css styling for about:serviceworkers page
/mozapps/downloads Description /mozapps/extensions Description
downloads.css styling for the "classic" downloads window about.css styling for the about window when right-clicking an add-on
unknownContentType.css styling for the unknown content handler blocklist.css styling for the blocklist
/mozapps/formautofill Description eula.css styling for providing an add-on's EULA
requestAutocomplete.css Unknown extensions.css main styling for the add-ons manager page (about:addons)
/mozapps/handling Description newaddon.css styling for the add-on confirmation page for suspiciously-enabled add-ons
handler.css Unknown selectAddons.css styling for add-on selection
update.css styling for the add-on updater
/mozapps/plugins Description /mozapps/profile Description
pluginProblem.css styling for plugin errors profileSelection.css styling for the profile selector
/mozapps/update Description /mozapps/viewsource Description
updates.css styling for the browser updater viewsource.css styling for the source viewer

Now that we've covered where particular styles are kept, let's get on with the creation, shall we?

Making your theme

When making your theme, be sure to have an idea in mind already for what you want the end result to look like, so you know what you're making. It may also help to do what is most likely the easier part of theme creation first: creating your images. As was stated earlier about CSS, you don't need to remake all the images. Most theme authors will change only the toolbar images (/browser/Toolbar.png and /browser/Toolbar-inverted.png), with maybe a few other additional icons changed in /global/icons. Icons in Toolbar.png are by default 18x18px, though you can use larger icons if you change the image region scanned by the theme (using the -moz-image-region property).

With the images out of the way, make your way to /browser/browser.css and start making your theme come to life.

  background: red;

Note that most times, RGB(A)/HSL(A) values are used instead of worded names, to be able to use a precise shade.

If you're finished here, and you're satisfied with the result, then you can start to distribute it.

Packaging your theme

You've done all the hard work and now just want to get it out to people; thankfully, this is quite simple in comparison!

To package a theme for release, place everything into a .zip file, and simply rename the extension to .xpi. Assuming both install.rdf and chrome.manifest were entered correctly, your theme will now install and you can freely distribute it. If you wish to distribute it in an official manner, on the Pale Moon Add-Ons Site, then please see the relevant page relating to that.

Happy theming!

Site design and Branding © 2024 Moonchild Productions - All rights reserved
Any other content, brand names or logos are copyright or trademark to their respective owners.
Policies: Cookies - User Content - Privacy.

The Pale Moon Developer Site is powered by Project Selene 1.2.1.