How to edit Gnome themes - Tutorial

Updated: May 17, 2017

Like the Rolling Stones song, I see some pale font and I want to paint it black. This is the primary motivation for me writing this article. How does one go about editing Gnome themes to make them more usable, i.e. better clarity and contrast, higher productivity, less eye and soul wear?

While Plasma offers a very simple and straightforward way to make theme changes through the system GUI, Gnome completely hides the functionality inside obscure files, with little to no standard on how they should look like or behave. Worry not, we will unravel the mystery today.


Gnome theme architecture

Let us briefly dwell on what Gnome themes are and what they look like. In a nutshell, these are glorified HTML files with their own defined styles kept inside CSS files. That is all, really. The rest is just bells and whistles. Think of your desktop as a giant, interactive Web page. Gnome themes are stored as folders with several sub-folders.  A typical Gnome theme will have the following:

<something optional>

Something optional refers to a folder with additional art. It may be called assets or alike, and it will contain images that form the part of the theme's decoration style, like buttons, borders, etc. Gtk-2.0 folder will contain settings and styles for old Gnome 2 and MATE desktops. The contents will include the gtkrc configuration file and possibly widgets. Gtk-3.0 folder will contain the gtk.css file that defines the look and behavior of the theme on the Gnome 3 desktop and its derivatives, like Cinnamon and Ubuntu's Unity.

The themes are stored in two locations. Globally, they go under /usr/share/themes. You will need root permissions to store new themes here, and the changes will affect all users running the particular theme. Locally, under ~/.themes, a hidden folder inside your home directory. This location is optional and may not exist on your system, and you will need to create it to store new themes there. It is the preferred way of managing themes, because you do not need root permissions, and the changes only affect your user.

Note: Occasionally, the Gnome convention of how themes are done and stored changes. The default Adwaita theme requires its own set of hacks, and changes may also be done through ~/.config/gtk-3.0/gtk.css.

Edit theme

So let's say you've decided to edit a theme. You just need to open the gtk.css file in a text editor and modify styles and their values. This is equivalent to designing a website and making changes that will affect the look, the color, the placement of elements.

Let's do a practical example. I decided to apply the Breeze theme to my Fedora 25 installation. This sounds like a cool trick, as you can enjoy KDE looks on Gnome and feel like the greatest libertine of open source. LIBERTINE. Get it?

The default theme is nice, but we have the Young Developer Syndrome (YDS). The font is too pale. Basically, gray on gray, which seems to be popular nowadays, probably because most software people are young, use huge monitors for their code work, and they do not spend as much time using their products as designing it, plus they have not been electrocuted enough.

Breeze applied

Font too pale

Let's edit the theme. As we've learned above, let's hack the CSS file. We want the font color. Which one, you may ask? Well, you can do an exercise. One, if you know CSS, you can guess the relevant CSS directive will be something like foreground (fg) color. If you do not, use the color picket in an imagine manipulation tool to select the text displayed in an element - screenshot it first. The corresponding hexadecimal value is what we want to change in the gtk.css file.

FG color

Here, we want to replace #31363b with #000000 (black) globally, for all instances that show in the CSS file. So it's a simple find & replace. However, please do BACKUP the file before making modifications. This way, you can always easily revert if something goes wrong.

CSS edit

Once you're happy, save the file. Then, re-apply the theme. You can apply something else, then go back to your theme. And here you have the final product before thy eyes, before and after:

Default font

Black font

The Gnome Tweak Tool window:

Breeze, modified

Breeze, modified, more

Of course, the edits are not limited to fonts. You can change background color, borders, margins, padding, anything you feel like. Do take into account that things will be drawn on a variety of displays and resolutions, so relative and/or hard-coded values will have their impact. Last but not the least, if you edit original themes under /usr/share/themes, they may get overwritten with system updates, and you will need to apply your changes again, so you might as well copy them and work on a separate instance.

Custom theme created

Some extra work

Now, with black fonts in Breeze, this calls for Droid Sans once again. You may wonder where, what and why, but I will follow up on this in a separate article, with lots of detail and drama.

Droid Sans fonts


Nice things come to those who tweak:

Nice 1

Nice 2

Nice 3

Nice 4


Exposing themes through a nice and safe GUI would be a great thing for end users. They don't need to be able to edit everything, but the basics of contrast and color should be available. Hacking themes through CSS files is not a sign of progress in 2017. We've gone a long way from simple and friendly to abstract and convoluted. This is what happens when you let people use Python and GOLANG. Tsk tsk.

Anyhow, I hope this article helps. Being able to use Gnome-based desktops comes with a price. The whole touchscreen-like happiness makes for a very generic usage model, and if you're not happy, tough shit. Ubuntu has fairly sane defaults, but neither Gnome nor Cinnamon do, and these account for a fair chunk of the Linux desktop base. Well, I hope the mystery and pain around Gnome 3 have vanished. Because, in essence, it's one giant web page. Hack those CSS files like there's no tomorrow. Welcome to the revolution.