Add-ons: Complete Themes

How to: Create a Complete Theme

Note: this guide might be outdated and in need of updating for current versions of the browser.

This guide was originally written by Lootyhoof, the forum topic can be found here.

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

THIS SECTION IS IN NEED OF A REWRITE -- it doesn't apply to the current versions of Pale Moon and you best bet would be to use an existing complete theme as a starting point.

The easiest way to set up the environment for themes (i.e. folder structure, base files) is to extract them from the default theme used in the browser. The files can be located as follows; extract using 7-Zip (or similar):

Windows:
- C:\Program Files\Pale Moon\omni.ja - extract /chrome/toolkit/skin/classic/global/ and /chrome/toolkit/skin/classic/mozapps/
- C:\Program Files\Pale Moon\browser\omni.ja - extract /chrome/browser/skin/classic/browser
Linux/Unix:
- Depending where you installed Pale Moon, this will be browser/omni.ja and omni.ja within the installation folder.
MacOS:
- Finder - Applications - Pale Moon - CTRL+Click - Show package contents - Content - Resources
- In this folder you will want browser/omni.ja and omni.ja.

Note that on Windows, if the Pale Moon folder is not located in Program Files, it might be in Program Files (x86), or in the location where you installed Pale Moon. Also note that the Aero theme is used due to additional stylings for Aero; it will still work on non-Aero systems (e.g. WinXP, Linux).

Once these three folders have been extracted somewhere, they should be placed in a new folder called chrome. As such, your current folder structure should be:

chrome

browser

[contents of /browser]

global

[contents of /global]

mozapps

[contents of /mozapps]

Aside from a few additional files to be added into the folder containing the chrome folder, this is the entire default theme, and will work perfectly. For these additional files, there will be a total of 3: install.rdf, chrome.manifest and icon.png. Let's start by making install.rdf. Copy the following into a text editor and save as "install.rdf", ensuring that it is not saved instead as "install.rdf.txt":

<?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">
    <em:id>id@here</em:id>
    <em:version>0.0.0</em:version>
    <em:name>Name Here</em:name>
    <em:description>Description Here</em:description>
    <em:creator>Your Name</em:creator>
    <em:type>4</em:type>
    <em:internalName>namehere</em:internalName>

    <em:targetApplication>
      <Description>
                <em:id>{8de7fcbb-c55c-4fbe-bfc5-fc555c87dbc4}</em:id>
        <em:minVersion>27.0.0b3</em:minVersion>
        <em:maxVersion>27.*</em:maxVersion>
      </Description>
    </em:targetApplication>
  </Description>
</RDF>

Please note that this will NOT work as-is, and is provided as template only. Please see the Install Manifests page for more information.

For chrome.manifest, copy the following into a text editor and save, replacing "namehere" with the same name you used in install.rdf:

skin browser namehere chrome/browser/
skin mozapps namehere chrome/mozapps/
skin global namehere chrome/global/

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/downloads	Description	/browser/feeds	Description
allDownloadsViewOverlay.css	styling for the all downloads view in the places window	subscribe.css	styling for the feed subscribe page
contentAreaDownloadsView.css	styling for about:downloads	subscribe-ui.css	styling for the controls on the feed subscribe page
downloads.css	general downloads styling, including both icons and popups for the downloads manager (only applicable if NOT using the "classic" download window)
/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)	menu.css	common styling for menus
aboutCache.css	styling for about:cache	menulist.css	common styling for menulists
aboutCacheEntry.css	styling for entries in about:cache	netError.css	common styling for various error pages
aboutMemory.css	styling for about:memory	notification.css	styling for notifications. (NOT including desktop notifications - see alert.css in /global/alert)
aboutReader.css	styling for reader view	numberbox.css	common styling for numberboxes
aboutSupport.css	styling for about:support	passwordmgr.css	styling for the password manager
appPicker.css	styling used for the dialog in selecting a default application	popup.css	styling for the notification popup
arrow.css	common styling for arrows	preferences.css	common styling for preferences windows
autocomplete.css	common styling for autocomplete (e.g. in urlbar)	printPageSetup.css	styling for the printer page setup dialog
buttton.css	common styling for buttons	printPreview.css	styling for the print preview dialog
checkbox.css	common styling for checkboxes	progressmeter.css	styling for progress meters
colorpicker.css	common styling for color pickers	radio.css	styling for radio buttons
commonDialog.css	common dialog styling	resizer.css	styling for the window resizer (usually shown in windows that can be resized)
config.css	styling for about:config	richlistbox.css	common styling for richlistboxes
customizeToolbar.css	styling for the "customize toolbar" dialog	scale.css	common styling for sliders
datetimepicker.css	common styling for date/time pickers	scrollbars.css	scrollbar styling
dialog.css	styling for dialogs	scrollbox.css	common styling for scrollboxes
dropmarker.css	common styling for dropmarkers	spinbuttons.css	common styling for spinbuttons
expander.css	common styling for expanders	splitter.css	common styling for splitters
filefield.css	common styling for file select fields	tabbox.css	common styling for tabboxes (groups of tabs, e.g. as seen in Preferences - Advanced)
filepicker.css	common styling for file pickers	tabprompts.css	styling for in-page alert boxes
findbar.css	find bar styling	textbox.css	common styling for textboxes
global.css	common styling for various UI elements (e.g. windows, dialogs, status bars, separators)	toolbar.css	common toolbar styling
groupbox.css	common styling for groupboxes	toolbarbutton.css	common toolbar button styling
inContentUI.css	common styling for "in-content pages (e.g. about:addons)	tree.css	common tree styling
linkTree.css	common styling for link trees	wizard.css	common wizard window styling (e.g. Migrator window)
listbox.css	common styling for listboxes
/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

Developer Tools (applies only to Pale Moon 27)

/global/devtools	Description	/global/devtools	Description
animationinspector.css	styling for the animation inspector panel	netmonitor.css	styling for the network monitor panel
canvasdebugger.css	styling for the canvas debugger panel	performance.css	styling for the performance watcher panel
commandline.css	styling for the GCLI developer toolbar (Shift + F2)	profiler.css	styling for the profiler panel
common.css	common styling for developer tools	ruleview.css	styling for rules view
computedview.css	styling for computed view tab	scratchpad.css	styling for the JS Scratchpad
dark-theme.css	styling for the developer tools when using the dark theme	shadereditor.css	styling for the shader editor
debugger.css	styling for the debugger panel	splitview.css	styling for split view
eyedropper.css	styling for the eyedropper	storage.css	styling for the storage panel
floating-scrollbars.css	custom styling for the scrollbars in developer tools	styleeditor.css	styling for the style editor (e.g. editing CSS files)
floating-scrollbars-light.css	custom styling for the scrollbars in developer tools (light theme)	timeline.css	styling for the timeline panel
font-inspector.css	styling for the font inspector panel	webaudioeditor.css	styling for the web audio editor panel
inspector.css	styling for inspector panel	webconsole.css	styling for the web console
layoutview.css	styling for layout view	webconsole_networkpanel.css	styling for the network section of the web console
light-theme.css	styling for the developer tools when using the light theme	widgets.css	styling for controls used in the developer tools (including icons)
markup-view.css	styling for the markup view
/global/devtools/appmanager	Description	/global/devtools/appmanager	Description
connection-footer.css	styling for app manager footer panel	projects.css	styling for project listing in app manager
device.css	styling for device listing in app manager
help.css	styling for help page of app manager	/global/devtools/projecteditor	Description
index.css	styling for app manager page	projecteditor.css	styling for project editor page

App Manager (deprecated) & Project Editor are inaccessible from the UI.

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!