Your submission was sent successfully! Close

Thank you for signing up for our newsletter!
In these regular emails you will find the latest updates from Canonical and upcoming events where you can meet our team.Close

Thank you for contacting our team. We will be in touch shortly.Close

  1. Blog
  2. Article

Graham Bancroft
on 23 November 2015

Vanilla: theme wrapping


If you’ve been following our Vanilla framework series of blog posts you’ll be aware of why we needed this new framework and have a little insight into how we’ve set about using it. With this post we’ll be delving a little further into how we include and customise the framework for our Ubuntu family of websites.

Let’s get started with how Vanilla fits into a site’s structure with an introduction to the concept of Vanilla theming.

Robin touched on how to use the framework in his recent post ‘Vanilla: Creating a modular Sass library’, to recap, in case you didn’t get that far, here’s how you get started.

In this example, we’ll start by installing Vanilla directly into your project. We’ll add the latest version of vanilla-framework to your project’s package.json as follows:

or, if you don’t have a package.json file go ahead and run the following:

Once you have Vanilla installed, your project will have a new folder called ‘node_modules’. An example of your code structure could be:

Some of our larger sites, such as www.ubuntu.com, are served using Django and we like to keep the folder structure as close to a standard setup as possible, therefore, all our static files are kept in a static folder.

To include Vanilla and all its essence (see what I did there?) you need to add the following to your site’s main scss file:

When you compile styles.scss it will include the framework into the compiled CSS. But what if I want to change the default colours? I hear you ask. Well, if you have a look in the vanilla-framework/scss/ folder you’ll see a file entitled _global-settings.scss, in this file you’ll discover the default theme settings such as brand colour and the maximum width of your site, this needs to be imported above the framework. However, if you are likely to use these styles on more than one site, you might want to consider building your own theme.

Building a theme

To take www.ubuntu.com as an example, where we are using ubuntu-vanilla-theme, the file structure looks like this:

Both the theme and framework are in nested folders called node_modules as Vanilla framework is a dependence of the theme. You’ll see in the ubuntu-vanilla-theme/scss folder there’s a file called _theme.scss, a theme specific _global-settings.scss file and a modules folder where any overrides of the vanilla-framework will live.

Here is an example of what _theme.scss could look like:

There’s a fair bit going on here but basically what we’re doing is pulling in our theme specific _global-settings.scss file with overrides and any new variables we may want to include, above the framework imports so any overrides we add will take effect. Now you can add new modules by creating files in /modules/, then add an @import and @include in your _theme.scss file.

You’ll also see that there is a build.scss file, this imports the theme file and includes the ubuntu-vanilla-theme mixin. We use Gulp as our build system to automate common tasks in the development of our websites. Coming up next in our Vanilla flavoured posts, Karl will be showing you how to build a theme.

Related posts


Igor Ljubuncic
24 January 2024

Canonical’s recipe for High Performance Computing

HPC HPC

In essence, High Performance Computing (HPC) is quite simple. Speed and scale. In practice, the concept is quite complex and hard to achieve. It is not dissimilar to what happens when you go from a regular car to a supercar or a hypercar – the challenges and problems you encounter at 100 km/h are vastly ...


Anthony Dillon
25 October 2023

Web team – hack week 2023

Design Article

Today, around 96% of software projects utilize open source in some way. The web team here at Canonical is passionate about Open source. We lead with an open-by-default approach and so almost everything we do and work on can be found publicly on the Canonical Github org. It is not enough to simply open our ...


Bartek Szopka
18 July 2023

Vanilla 4.0 release

Design Article

Last week we released a new major version of the Vanilla framework. Vanilla 4.0 introduces the elements of the new style used for a current rebranding of Canonical’s brochure websites, including typography changes of headings utilising new variable Ubuntu font, wider grid width, removed rounded corners, some updated colours, and updates t ...