You Got A Question? Ask    GNOME Community!

Making GTK3 themes – Part 1: Basics

This post was made with an older stylesheet

The new trend is to use the web technologies everywhere, be it smartphone or desktop. Web technologies are generally easier, and that’s why they are so widespread.  So what it has to do about GTK3 themes? A lot, because GTK3 themes use CSS syntax, which is widely used in the web. CSS stands for Cascading Style Sheets. The CSS syntax is very easy to understand and and use. For example, if we want to set a blue background and white text color in a paragraph (represented as <p> in HTML), the CSS syntax will be,

p {
background-color: blue;
color: white;

We won’t go into details of CSS and assume you learnt it already. If not, w3schools is a quite good place to start. Let’s discuss about GTK3 themes instead. Also check, it has some good resources.

I believe that we cannot learn everything from tutorials. We learn as we do. So I shall not only write a tutorial here, but also guide you through creating a theme. But will do it from next part. Just basics for today :D

Directories and files

When a GTK3 app starts, it will load certain files. First it tries to load the file $XDG_CONFIG_HOME/gtk-3.0/gtk.css if it exists (usually ~/.config/gtk-3.0/gtk.css). Then, tries to load ~/.themes/name/gtk-3.0/gtk.css. And lastly, tries to $datadir/share/themes/name/gtk-3.0/gtk.css (usually /usr/share/themes/name/gtk-3.0/gtk.css), where “name” stands for the name of the current theme. What does it mean? It means if you place a theme in /usr/share/themes/ and a modified one in ~/.themes/, the one in ~/.themes is used. Note that if you place a theme in /usr/share/themes, then it will be available for all users, but if you place it in ~/.themes, then it will be only available to you.

So basically we have our theme in ~/.themes and the GTK3 part in ~/.themes/name/gtk-3.0.

Theme engine

The look of your theme may vary depending on what engine you use. Different theme engines may provide different features than the default engine. Additional features provided by an engine is generally registered with a prefix, similar to vendor prefixes in the Web (We’ll discuss it later). So choosing the right theme engine is necessary.

Currently, you have 3 options,

  1. Use the default built-in engine
  2. Use the Adwaita engine
  3. Use the Unico engine

So which one should you choose? Let’s look at the advantages of different engines.

The default built-in engine

You can do a complete full featured theme with the default engine. the syntax is similar to pure CSS and there are no engine specific prefixes. It offers standard features like multiple inset box shadows, gradients etc.

With the default engine, you might also experience few quirks. Such as the scale slider doesn’t look so good. The focus border is a dotted line and seems that we cannot change or disable it.

Examples: EvolveAlbatross

The Adwaita engine

Adwaita offers some advantages over the default engine like customizable focus borders, border gradients etc. Also you won’t experience much quirks here.

Examples: AdwaitaGnomish Gray etc.

The Unico engine

Unico offers many new features. For example customizable focus borders and focus fill, border gradients, inner strokes, outer strokes, glows etc. But seems that box shadow is not supported in Unico. So you will need to use lots of engine specific prefixes. And it can be more difficult for you to port to another engine. Also I hear that the Unico engine will be abandoned. So think twice before you decide to use Unico. As far as i can tell, you’ll only miss outer strokes.

Examples: AmbianceZukitwoElementary etc.

So I won’t make this post any longer. We’ll start making our dream theme on the next post. :D

Part 2 | Part 3 | Part 4

  We can't watch comments unless G+ provides an API or if you send a notification, e.g +World Of Gnome
     Sometimes is better to place your questions on GNOME Community
  • Valerio

    Thanks Satya I love this series! 

    • Satyajit Sahoo

      Thanks :D

  • Augustine Souza

    Looking forward to more. I hope you keep it as simple as possible :)
    I’m not interested in making a whole new theme of my own, but I would like to know how to make minor modifications to themes that I use. One specific interest that I have is to increase the contrast between the “thumb” and the background of the Chrome browser without losing the ability to see the little horizontal bars that appear in the vertical Chrome scrollbar when doing a find (ctrl+F). I hope you have some magic for that!

    • Alexandros Mittos

      “I’m not interested in making a whole new theme of my own, but I would like to know how to make minor modifications to themes that I use” 


      • Satyajit Sahoo

        That’s the same thing. In both cases you’ll need to know how a theme works.

    • Satyajit Sahoo

      Chrome is GTK2 (even not fully native) and I’ll be writing about GTK3.

  • Alexandros Mittos

    Awesome! Keep up the good work, satya and WoGue! :-) 

    • Satyajit Sahoo

      You are welcome.

  • Pingback: Links 18/7/2012: KDE Workspaces 4.9, Raspbian | Techrights()

  • Andrew M

    Recent Linux convert here running Ubuntu 12.04 LTS, and I am becoming VERY interested in making my own theme considering how much CSS I know. Looking forward to the next article in the series!

    • Satyajit Sahoo

      Soon :D

  • Pingback: Making GTK3 themes – Part 2: The gtk.css and gtk-widgets.css files | woGue()

  • Pingback: Making GTK3 themes | kepica Blog()

  • Pingback: Making GTK3 themes – Part 3: The dark side [READY] | woGue()

  • Pingback: Making GTK3 themes – Part 4: Porting GTK2 themes | woGue()

  • hellzou

    Interesting article. I really keep liking wogue.