How to: Create a Complete Theme

Post your tutorials for using Pale Moon or performing related tasks here.
Note: Not for "how do I...?" Questions!
Forum rules
Tutorials and Howtos should only relate to Pale Moon, and not to third party applications. e.g.: Don't post a Howto for configuring your firewall.
If you have a question how to do something, you should use one of the support boards, not this board. It is meant for people to document and post instructions.
User avatar
Posts: 1466
Joined: 2012-02-09, 23:35
Location: United Kingdom

How to: Create a Complete Theme

Post by Lootyhoof » 2015-11-14, 20:42

Given the current lack of (user-friendly) documentation currently regarding Complete Theme creation, I figured it would be best to create my own. :)

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
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):

C:\Program Files\Pale Moon\omni.ja - extract /chrome/toolkit/skin/classic/aero/global/ and /chrome/toolkit/skin/classic/aero/mozapps/
C:\Program Files\Pale Moon\browser\omni.ja - extract /chrome/browser/skin/aero/browser

*nix users will find these files instead at /opt/palemoon/omni.ja and /opt/palemoon/browser/omni.ja respectively.

Note that if the Pale Moon folder is not located in Program Files, it might be in Program Files (x86). 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:

|__ 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":

Code: Select all

<?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">
    <em:name>Name Here</em:name>
    <em:description>Description Here</em:description>
    <em:creator>Your Name</em:creator>

        <!-- Pale Moon -->
Please note that this will NOT work as-is, and is provided as template only. Please see the Install Manifests page over at Mozilla 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:

Code: Select all

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, or, "What is this?!"
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:

aboutCertError.css - styling for SSL error pages
aboutPrivateBrowsing.css - styling for the private browsing information page
aboutSessionRestore.css - styling for the session restore page
aboutSocialError.css - styling for social errors page. Unused
aboutSyncTabs.css - styling for the synced tabs page
browser.css - main browser styling (e.g. tab styles, toolbar icons, etc). This is the one most people will want to edit. :)
engineManager.css - styling for the search engine manager window
pageInfo.css - styling for the page info window
sanitizeDialog.css - styling for the "clear recent history" window
searchbar.css - search bar styling (buttons etc; main styling is in browser.css)
setDesktopBackground.css - styling for the "set desktop background" window
syncCommon.css - common styling for sync dialogs
syncProgress.css - styling for sync progress
syncQuota.css - styling for sync quota
syncSetup.css - styling for sync setup dialog

commandline.css - styling for the command line (shift + F2) developer tools
common.css - common styling for devtools
computedview.css - styling for the computed view tab of devtools
dark-theme.css - dark styling for devtools
debugger.css - styling for the debugger
font-inspector.css - styling for the font inspector
inspector.css - styling for the inspector
layoutview.css - layout view styling
light-theme.css - light styling for devtools
markup-view.css - styling for the markup view
netmonitor.css - styling for the network monitor
orion.css - styling for the source editor (Scratchpad/Style Editor)
orion-container.css - styling for the source editor's container
profiler.css - styling for the profiler
ruleview.css - styling for the rules view
scratchpad.css - styling for scratchpad
splitview.css - split view styling
webconsole.css - web console styling
webconsole_networkpanel.css - styling for the network section of the web console
widgets.css - stylings for controls in devtools (including icons)

allDownloadsViewOverlay.css - styling for the all downloads view in places (history/bookmarks manager)
contentAreaDownloadsView.css - styling for about:downloads
downloads.css - general downloads styling, including both icons and popups for the downloads manager (only applicable if NOT using the "classic" download window)

subscribe.css - styling for the feed subscribe page
subscribe-ui.css - styling for the controls on the feed subscribe page

newTab.css - styling for the new tab page

editBookmarkOverlay.css - styling for the "edit bookmark" dialog used when clicking on the bookmark button on an already-bookmarked site
organiser.css - styling for the toolbars/menus in the places window (history/bookmarks manager)
places.css - styling for the content of the places window

aboutPermissions.css - styling for about:permissions
applications.css - styling for the applications tab in Options
preferences.css - styling for the Options window

about.css - common styling for "About" pages (e.g. about:about)
aboutCache.css - styling for about:cache
aboutCacheEntry.css - styling for entries in about:cache
aboutMemory.css - styling for about:memory
aboutSupport.css - styling for about:support
appPicker.css - styling used for the dialog for selecting a default application that is not listed when in the application tab in Options
arrow.css - common styling for arrows
autocomplete.css - common styling for autocomplete (e.g. in urlbar)
button.css - common styling for buttons
checkbox.css - common styling for checkboxes
colorpicker.css - common styling for color pickers
commonDialog.css - common dialog styling
config.css - styling for about:config
customizeToolbar.css - styling for the "customize toolbar" dialog
datetimepicker.css - common styling for date/timer pickers
dialog.css - styling for dialogs
expander.css - common styling for expanders
filefield.css - common styling for filefields
filepicker.css - common styling for filepickers
findBar.css - find bar styling
global.css - common styling for various UI elements (e.g. windows, dialogs, statusbars, separators)
groupbox.css - common styling for groupboxes
inContentUI.css - common styling for "in-content" pages (e.g. about:addons)
linkTree.css - common styling for link trees
listbox.css - common styling for listboxes
menu.css - common styling for menus
menulist - common styling for menulists
netError.css - common styling for various error pages
notification.css - styling for notifications (not including desktop notifications - see alert.css in /global/alert)
numberbox.css - common styling for numberboxes
passwordmgr.css - styling for the password manager
popup.css - styling for the notification popup
preferences.css - common styling for preferences windows
printPageSetup.css - styling for the printer page setup dialog
printPreview.css - styling for the print preview dialog
progressmeter.css - styling for progress meters
radio.css - styling for radio buttons
resizer.css - styling for the window resizer
richlistbox.css - common styling for richlistboxes
scale.css - common styling for sliders
scrollbars.css - scrollbar styling
scrollbox.css - common styling for scrollboxes
spinbuttons.css - common styling for spinbuttons
splitter.css - common styling for splitters
tabbox.css - common styling for tabboxes (groups of tabs, e.g. as seen in Options - Advanced)
tabprompts.css - styling for in-page alert boxes
textbox.css - common styling for textboxes
toolbar.css - common toolbar styling
toolbarbutton.css - common toolbar button styling
tree.css - common tree styling
wizard.css - common wizard styling

alert.css - styling for desktop notifications

console.css - styling for the error console

dirListing.css - styling for directory listings

TopLevelImageDocument.css - styling for pages when viewing individual images
TopLevelVideoDocument.css - styling for pages when viewing individual videos
videocontrols.css - styling for HTML5 native video

downloads.css - styling for the "classic" downloads window
unknownContentType.css - styling for the unknown content handler

about.css - styling for the about window when right clicking an addon
blocklist.css - styling for the blocklist
eula.css - styling for providing an addon's EULA
extensions.css - main styling for about:addons
newaddon.css - styling for the addon confirmation page for suspiciously-enabled addons
selectAddon.css - styling for addon selection
update.css - styling for the addon updater

handler.css - ?

pluginProblems.css - styling for plugin errors

profileSelection.css - styling for the profile selector

updates.css - styling for the browser updater

viewsource.css - styling for the source viewer

xpinstallConfirm.css - styling for the addon install popup

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. :) In order to know what the elements are called (and so be able to find their stylings in browser.css to change them), I would highly recommend the DOM Inspector and Element Inspector addons, to be able to press shift + right click on browser elements. Then, once the element is found in the CSS, you are free to style it as you please, until you manage to create a theme that you are satisfied with. For example, if you wanted to make the navigation bar red, you would enter the following:

Code: Select all

  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 thread relating to that.

Happy theming! :thumbup: