GNOME SHELL THEME PACKAGING SPECIFICATION ========================================= Version: d2.0 (April 29th 2011) Purpose (non-normative) ---------------------- The purpose of this specification is to provide clear guidance to both developers of themes for the GNOME Shell and developers of theme selectors for the GNOME Shell of how such themes shall be packaged to facilitiate interoperability between theme packages and theme selectors. The primary goal of this specification is that a user should be able to replace one theme selector with another and it "just works". A secondary goal is that a user should not have to interact with the contents of a theme package during installation other than selecting a theme package to install or, when deleting a theme, the theme to delete. Scope ----- This specification is for GNOME Shell themes and does not include theming of applications running in the GNOME Shell or the windows within such applications are displayed by the GNOME Shell. The files that actually form the theme are also outside the scope of this specification. Contents of a GNOME Shell Theme Package --------------------------------------- 1. A theme package shall consist of the following: - a theme metadata file - a theme preview image file - a theme stylesheet file together with the actual theme image files. Other files such as a README or LICENSE may be included. 2. The theme metadata file, theme preview image file and theme stylesheet file and the actual theme image files shall be in the //gnome-shell/ directory of the theme package where is the name of the theme. Other files, if included, may be in a directory under //gnome-shell. 3. The contents of a theme package shall not be dependent on, or make any assumptions about, being installed in a specific location on a host filesystem. 4. A theme metadata file shall be in JSON format and only contain characters from the POSIX Portable Character Set. It shall contain the following name/value pairs: name: [string] The short name for a theme. Max 32 characters. author: [string] The name of the theme developer. Max 32 characters. version: [string] A version number for the theme. type: [string] Theme type. This shall always be 'custom'. Other values are reserved for use by theme selectors. thumbnail: [string] The name of the file containing the theme preview image. It may contain the following optional name/value pairs: disabled: [boolean] True or false. Designates whether a theme should be presented in the theme selector. shell-version: [string] Restrict the theme to specific version(s) of the GNOME Shell. gjs-version: [string] Restrict the theme to specific version(s) of GNOME JavaScript. A theme selector shall honor optional name/value pairs if present in a theme metadata file. It may not contain the following name/value pairs which are reserved for future use: engine: [string] Theme engine to use. stylesheet: [string] Presentation stylesheet to use. Other name/value pairs may be included in the theme metadata file but a theme selector may ignore such name/value pairs. The name/value pairs shall be wrapped within a JSON object as follows: { "shell-theme": { REQUIRED AND OPTIONAL NAME/VALUE PAIRS } } The order of name/pairs is not significant. 5. A theme preview image shall be sized for optimal viewing at a height and width of 128 x 96 pixels. The image format shall be either PNG (Portable Network Graphics) or SVG (Scalable Vector Graphics). If the format is PNG, the filename shall have an extension of .png. If the format is SVG, the filename shall have an extension of .svg. 6. A theme stylesheet shall be named "gnome-shell.css". The theme stylesheet may not include other stylesheets. 7. A theme package shall be compressed into a ZIP archive. The filename of the archive shall be less than 64 characters in length. The filename shall incorporate the name of the theme, the version numberi of the theme and shall have an extension of .zip. 8. All filenames shall contain no white space, shall not start with an underbar, and shall only contain characters from the POSIX Portable Character Set. Examples [non-normative] ------------------------ Here is an example of the contents of a conforming theme metadata file: { "shell-theme": { "name": "Isulan", "author": "Half-Right", "description": "Another beautiful theme from Half-Right", "version": "1.0", "type": "custom", "thumbnail": "preview.png", "url": "http://example.com/isulan" } } Here is an example of a conforming theme package filename: Isulan_v1.0_by_Half-Right.zip Here is an example of the layout of a conforming theme package /Isulan /Isulan/gnome-shell/theme.json /Isulan/gnome-shell/preview.png /Isulan/gnome-shell/gnome-shell.css /Isulan/gnome-shell/calendar-arrow-left.svg /Isulan/gnome-shell/calendar-arrow-right.svg /Isulan/gnome-shell/close.svg /Isulan/gnome-shell/close-window.svg /Isulan/gnome-shell/corner-ripple.png /Isulan/gnome-shell/dash-placeholder.svg /Isulan/gnome-shell/filter-selected.svg /Isulan/gnome-shell/preview-atolm.png /Isulan/gnome-shell/process-working.png /Isulan/gnome-shell/process-working.svg /Isulan/gnome-shell/toggle-off-intl.svg /Isulan/gnome-shell/toggle-off-us.svg /Isulan/gnome-shell/toggle-on-intl.svg /Isulan/gnome-shell/toggle-on-us.svg /Isulan/gnome-shell/ws-switch-arrow-down.svg /Isulan/gnome-shell/ws-switch-arrow-up.svg