Linux Applications

How does GNOME themes work

The GNOME themes file is essentially a CSS file; the theme files describe what your desktop looks like but that is not all. It also contains the artwork needed for it to work. You make all your configuration in the CSS file of your theme. A caveat is that much of the look comes from the GTK 2.0 and GTK 3.0 themes. Another issue is that the standard setup does not allow your own themes, you need to download the User Theme extension to use your own theme. The reason is that the theme files delivered with your distribution are compiled from gresource files. This integrates the themes closer to the development process but has the drawback that making your own requires more programming skills. Documentation is also scarce, for users that is. Development documentation is plentiful.

The format of the package

When you want to change your GNOME desktop, you can do so with theme files that you choose from ‘Appearance’ in the Tweaks interface. Here, you will find that you can choose between ‘Applications’, ‘Cursor’, ‘Icons’ and ‘Shell’. This gives you all the flexibility you need but it may look strange when you change the shell theme and have no application theme. To solve this, you need all the themes to match. Many themes contain only the shell or only the GTK+ (Application) part.

You can also create your own icons and pack them in a standard file. You can run in to similar problems here. If you have icons or fonts that do not match your theme, at best it looks silly. In some cases text will not be visible because icons and background are the same colour.

Packed files

The many files, fonts and decorations you need, are stored in the below user directories.

Icons: Unzip Icons in ~/.icons folder GTK/Shell Theme: Unzip GTK and Shell themes in ~/.themes folder Cursor: Unzip Cursor themes in ~/.icons folder Fonts: Unzip Fonts in ~/.fonts folder

A full theme has all these files built in and contains a file: index.theme. The files points out all the files to ensure that you can have a your icons match font style. You will also make the applications look like they match each other.


This code shows the different themes you want to use. There are more details for this file so make sure you look here when you use theme. This way, you get the best look for you. To switch to the specific theme, you need to change the values one by one.

What is the files format?

In each theme, you have a structure of directories. These directories contain the resources that your CSS files point to. You should use existing standards to make it easier for users of the theme. A good example is the Forest theme, the tree is below.


└── gnome-shell
├── common-assets
│ ├── dash
│ ├── menu
│ ├── misc
│ ├── panel
│ └── switch
├── dark-assets
│ ├── checkbox
│ ├── menu
│ ├── misc
│ └── switch
├── gnome-shell.css

12 directories, 2 files

Here, you can see the gnome-shell.css file. Those files tend to get long because it points out all elements on the desktop. However, there is method to the madness so follow along with a few examples. The code uses all the common CSS functions, a dot (.) for classes and a hash (#) for named elements. They group these to create an even look.

Inside the files, you have names of all the boxes and icons. You can see how they work through a toolkit, called St (Shell Toolkit). From the main StWidget, the system creates StEntry, StButton and StDrawing Area, plus a few others. Knowing this, you can understand what you are looking at in the CSS. While you look be prepared to look up things in the documentation, though knowing some basics will help you navigate better.

.check-box StBoxLayout {
spacing: .8em; }
.check-box StBin {
width: 16px;
height: 16px;
background-image: url("dark-assets/checkbox/checkbox-unchecked.svg"); }
.check-box:focus StBin {
background-image: url("dark-assets/checkbox/checkbox-unchecked-focused.svg"); }
.check-box:checked StBin {
background-image: url("dark-assets/checkbox/checkbox-checked.svg"); }
.check-box:focus:checked StBin {
background-image: url("dark-assets/checkbox/checkbox-checked-focused.svg"); }

The code above, from the Forest-Dark theme, shows the definition of a checkbox that uses the StBin for its definition. Most of the names will be obvious from their names. However, if you are uncertain, check GNOME Documents for guidance. The best strategy to make your own theme is to base it on an existing one and edit it to your own taste.

What image formats are supported?

The file format for all graphical components can be SVG and PNG. The best is to use SVG since it scales better for different sizes. This is also the most commonly used. Even though, the format scales well, make sure to test it in many scales. The graphic itself also has to be designed to be clear in all supported scales.

What else do I need to create a theme?

Most of a theme is created by writing correct CSS but when you want to have your own icons, you need more. For Linux, you have Inkscape to create SVG graphics. It will be beneficial to have your favourite code editor, it helps a lot when you hack CSS. The idea is to code using web technologies after all.

Where do I find examples and tutorials?

Most existing projects are available on, though many beautiful themes are also available on Deviant art. There are a few tutorials but most of them are how to install a new theme you downloaded. Below is a good start to explore themes.


It is great to be able to tweak your desktop environment; this is what you stare at all day. With themes for GNOME, you can do it in every detail. Remember, your desktop is a complex beast so be prepared to learn and start with a template or an existing project.

About the author

Mats Tage Axelsson

I am a freelance writer for Linux magazines. I enjoy finding out what is possible under Linux and how we can all chip in to improve it. I also cover renewable energy and the new way the grid operates. You can find more of my writing on my blog.