dev builds
themes manual
device status forums
mailing lists
IRC bugs
dev guide

Search | Go
Wiki > Main > ThemeGuidelines

Guidelines for Submitting Themes

(We like to think of them more as rules)

Theme Name

Please don't include the platform name in the theme title. On the Wiki, and on this site, all themes are stored according to the devices they are compatible with and having "Nano" or "SansaE200" in every theme name is just silly.

File Structure

All uploaded themes must be in a zip file.

Inside your zip file must be a folder called .rockbox, and inside this folder 'backdrops', 'fonts', 'themes', 'icons' & wps folders as appropriate- all lowercase. Case is important... If you don't exactly match file and path names on unix based platforms (when running a sim for example) the theme will fail to load.

The zip file must not include junk files:
  • examples: thumbs.db , desktop.ini, .DS_Store, .directory etc.
If you created the zip file in a Windows based PC, check inside the backdrops and wps folders for 'thumbs.db' files - these can be deleted as they serve no use to anyone else, and just take up disk space on the device (sometimes several hundreds of kilobytes!)

This zip file should be named to match your theme. If you are dealing with a theme that is for multiple platforms, or are converting an existing theme to a new platform, then including the platform name in the zip filename is fine. Once submitted to this site, that portion of the filename will almost always be removed before uploading.

File Naming

Remember, not everyone will want to load the whole of your theme, they may like to 'mix and match' with a wps from one theme, a backdrop from another etc., so please try to name your backgrounds, wps's and themes consistently.

A bad example
       #My sample theme - mymates.cfg 
       wps: /.rockbox/wps/myfirstwps.wps
       font: /.rockbox/fonts/snap.fnt
       backdrop: /.rockbox/backdrops/johnandstuart.bmp
       iconset: /.rockbox/icons/silk.18x17x16.bmp
       viewers iconset: /.rockbox/icons/tango_viewers.20x16x16.bmp
       foreground color: 000000

This would make it difficult for someone to easily know which backdrop is being used by this theme, and makes removing the theme from your device just that little more difficult and could create problems with text legibility if the previous theme had set 000000 as the backgound color

       #Theme Name: Killers 
       #By: (MrCoolNick on IRC)
       #Platform: iPod Video (320x240x16) - Standard build
       #Version: 0.1 beta
       #Licensed CC-BY-SA 3.0
       #Graphics taken from
       #Last updated: Wed, 16th May 2007 17:22 CEST
       wps: /.rockbox/wps/mymates.wps
       font: /.rockbox/fonts/snap.fnt
       backdrop: /.rockbox/backdrops/mymates.bmp
       iconset: /.rockbox/icons/silk.18x17x16.bmp
       viewers iconset: /.rockbox/icons/tango_viewers.20x16x16.bmp
       foreground color: 000000
       background color: FFFFFF

It is now easy to see which backdrop and wps are being used by this theme, and the text would always be readable regardless of what colours had been previously set. In addition the header gives more information about the theme, and who to contact in the event of problems.

Colours and Backdrops

Put simply - ALWAYS set both a foreground and background color, and ensure that they have sufficient contrast to be readable without your background images being loaded. If you load a coloured background on your wps and a coloured backdrop in the menu, you will obviously need to change the forground colour selected in your theme - it would be unreadable otherwise - but you should also set the background colour to a contrasting shade, else when another theme is loaded that assumes the default dark on light colour scheme, the text can become unreadable.

Text Translation

Consider including text translation support in your theme. If you have any text in your theme such as "Artist", "Title" or "Track", use the %Sx tag so that it gets translated to the current language. For example, instead of Track %pp of %pe, use %Sx(Track) %pp %Sx(of) %pe. For more information, refer to WPS Tags section of the RockBox manual. Check in the english.lang language file to see if the text to be translated is included.

Patches and Builds

Some themes will not work with the official build, and it is expected that the theme author lists the patches required to use the theme. A list of Flyspray entries by number and links will suffice. It would also be a great benefit to novice users if a suitable Unsupported Build is specified.


Please consider building a version number into your theme - either in a comment or as a separate text file inside the zip, along with a date.


If you want your theme to be part of the Rockbox collection it is expected that the theme has a clear license. The new standard is CC-BY-SA. Themes not posted with a permissive license will be removed from the wiki. Themes not using CC-BY-SA will not be transferred to the replacement themes website. No one can modify material from your theme if it is not published with a suitable license. Please make sure that any 3rd party images have an appropriate license (granting re-use and/or modification). For some sources of images published with a clear license see FreeImages.


If you feel that any file or files on violates your copyright, please view the DMCA 17 USC § 512 for the proper procedure. If we become aware that one of our users is a repeat copyright infringer, it is our policy to take reasonable steps within our power to prevent them from uploading further.

r23 - 02 Apr 2021 - 20:46:07 - UnknownUser

Copyright © by the contributing authors.