Add-ons: Complete Themes

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
   - http://mozilla.org/MPL/2.0/. -->

<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:em="http://www.mozilla.org/2004/em-rdf#">

  <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:id>your_id@goes.here</em:id>
        <em:version>1.0.0</em:version>
        <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>
        <em:type>4</em:type>
    <!-- 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. -->
    <em:internalName>theme-template</em:internalName>
    <!-- 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. -->
    <em:skinnable>true</em:skinnable>

    <em:targetApplication>
            <Description>
        <em:id>{8de7fcbb-c55c-4fbe-bfc5-fc555c87dbc4}</em:id>
        <em:minVersion>31.0.0</em:minVersion>
        <em:maxVersion>31.*</em:maxVersion>
      </Description>
    </em:targetApplication>

  </Description>
</RDF>

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.

#nav-bar
  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!