Theming Gnome Shell with Sass and Gulp

I love Linux, and am a big fan of Gnome Shell. I recently set out to create my own theme for Gnome Shell, and since I work for Four Kitchens, I decided it would be cool to use the Four Kitchens branding as my color palette. I haven’t really applied that much branding yet, but I thought I’d write a quick post about how I set up the theme with Sass and Gulp. (See the project on my Github profile).

Getting Gnome Shell and user themes set up

First off, you obviously need to have Gnome Shell installed and running. I use the ubuntugnome distro, but if you don’t have gnome shell installed go ahead and install it. (Instructions for Ubuntu 14.04).

Secondly, you need to have gnome-tweak-tool installed. I think it comes by default with gnome shell > 3.10, but if you don’t have it, go ahead and

And finally, go ahead and turn on User Themes in gnome-tweak-tool. To do this, launch gnome-tweak-tool, and go to the extensions tab. Scroll down the list of extensions, and turn “User Themes” on.

Setting up your theme

Make a ./themes directory under your home directory. This is where you will put your user themes. Then create another folder for your theme, and another folder inside your folder called gnome-shell. Inside gnome-shell, you’ll put the gnome-shell.css file, and the assets for your Gnome Shell theme. Just for the record, here’s the folder structure:

mkdir ~/.themes
mkdir ~/.themes/theme-name
mkdir ~/.themes/theme-name/gnome-shell

For your theme to be recognized by Gnome Shell, you’ll need to have a gnome-shell.css file in your ~/.themes/theme-name/gnome-shell folder. Since you probably don’t want to write all the styling and positioning for Gnome Shell, and most likely just want to override the styling for certain elements, include this at the top of your css file:

@import url("/usr/share/gnome-shell/theme/gnome-shell.css");

That will pull in the default Gnome Shell style sheet.

Once you’ve created your theme folders, and have a gnome-shell.css file, you should be able to go into gnome-tweak-tool, so under the “Appearance” tab set “Shell Theme” to your theme. You could start writing your theme css in that file, but we’re going to add Sass to the project, because styling Gnome Shell is going to take a lot of css.

Sass and Gulp

Sass is a powerful tool for writing stylesheets, and gulp is a command line javascript-based task runner. Using gulp, you can compile sass files into ~/.themes/theme-name/gnome-shell/gnome-shell.css. If you don’t have sass and gulp installed, follow the links and install them both.

Gulp

To have gulp compile sass, you’ll need to have a package.json file in your theme root that tells npm what it needs to install. Here’s an example from the theme I’m building:

{
  "name": "fourkitchens-gnomeshell",
  "version": "1.0.0",
  "repository": "https://github.com/patrickocoffeyo/fourkitchens-gnomeshell.git",
  "dependencies": {},
  "devDependencies": {
    "gulp": "^3.6.2",
    "gulp-ruby-sass": "^0.5.0"
  },
  "engines": {
    "node": ">=0.8.0"
  }
}

Once your project dependencies have been defined, run npm install in your theme root. After this successfully completes, you’ll be all set to have gulp compile sass. So let’s create some sass files ‘real quick. Make a sass directory in your theme root (~/.themes/theme-name/sass). Put a file in there called gnome-shell.scss and add the @import url("/usr/share/gnome-shell/theme/gnome-shell.css"); line to the top of it. You can add sass to this file, or, like I did in my project, you can separate your styling out in to different files. I’m organizing my sass by component. There’s a file for the dash, and the panel, and a variables.scss file that holds the color/spacing variables for other files, and all these files are included in my gnome-shell.scss file.

Now it’s time to set up gulp to compile sass. For that, you’ll need a gulpfile.js file in your theme root. There is a lot of official documentation for writing gulpfiles, so I won’t try to re-write all of that here, but here’s the gulpfile for my theme:

var gulp = require('gulp');

// Include plugins
var sass = sass = require('gulp-ruby-sass');

// Compile Our Sass
gulp.task('sass', function() {
  return gulp.src('sass/gnome-shell.scss')
    .pipe(sass({
      style: 'expanded'
    }))
    .pipe(gulp.dest('gnome-shell'))
});

gulp.task('default', function () {
  gulp.watch('sass/*.scss', ['sass']);
});

This basically takes the sass/gnome-shell.scss file and compiles it to gnome-shell/gnome-shell.css. You can run gulp sass in your theme root to run the sass task, or you can run gulp default to watch changes to your sass files, and automatically compile when changes are made.

Loading your theme

When you make changes to your theme, you’ll need to let Gnome Shell know, so that it can reload the styling. To do that, press alt+f2 on your keyboard, and type rt into the command prompt that appears. Then press enter. Gnome Shell will reload your theme. 🙂

Once you have everything set up, you should be able to easily write to your sass files, reload your theme, and style your desktop interface. Here’s a snapshot of my Four Kitchens theme so far:

That’s pretty much it! Good luck!

This post was originally published on my personal blog here.