Our first Drupal 8 theme

Created on
Updated on
Written By
Our first Drupal 8 theme

Case study

Over the last few months we have been more and more excited about the upcoming version of Drupal. Drupal 8 brings plenty of innovations for the content editor, the backend developer or the themer. But today we are going to discuss the really cool stuff from a front-end perspective. The biggest improvements are definitively twig, YAML and the new javascript integration.


Twig has replaced PHPTemplate as the default theming engine for Drupal 8. This improves and optimizes the theme layer logic. It will make it safer, smaller, faster and easier to understand. Drupal 8 makes the theming more approachable to a wider audience which is good for the community. By the way twig offer a great integration with the most popular IDEs and this is pretty handy.

YAML is a powerful and human readable data serialisation format. Most of Drupal 8 config files are now written in YAML.

Drupal 8 introduces a few new Javascript libraries like underscore.jsbackbone.jsmodernizrjQuery2CKeditor and Joyride which make it into the core. But the really good news is that Drupal will not load any Javascript by default. Unless specified otherwise Drupal 8 will load zero byte of Javascript.

To get a better understanding of the new features we decided that the best way was to create a simple, clean and flexible base theme. We call it "Prius" and is currently supporting this website. You can get the code from drupal.org or check the online demo. We will cover some cool features of our theme but feel free to dig into the code. To build our new Drupal 8 theme we have packaged it with some of the latest awesomeness we have been working with:

  • SASS because writing plain CSS is just a pain.
  • SMACS to better organise your stylesheet and make their maintenance easier.
  • Suzy in its second release to build a powerful grid system.
  • Breakpoint media queries for your responsive design.
  • Compass vertical rhythm typography.
  • SyntaxHighlighter for the code syntax highlighting.
  • Font Awesome Icons.
  • Some Google Fonts.
  • Some polyfill to make your website looks decent in IE6-8.
  • A Grunt script to automate your font-end tasks (concat, uglify, optimize images)


We are now supporting Drupal 8 alpha14. You also need to have the latest packages for sass (>= 3.3) and compass (>= 1.0). We are currently using compass 1.0.0.alpha.19 and sass 3.3.4.

  # sass -v
  # compass -v


CSS3 is the latest standard for CSS but is not supported in older browsers. Enabling selectivizr will emulate support for CSS3 pseudo-classes and attribute selectors in Internet Explorer 6-8. It is done by creating a new bundle in the prius.libraries.yml and enable it in the prius.info.yml.

# prius.info.yml
# Enable prius-selectivizr javascript bundle
  - selectivizr
# prius.libraries.yml
# Emulates CSS3 pseudo-classes and attribute selectors for IE 6-8.
  remote: http://selectivizr.com/
  version: 1.0.2
    name: MIT
    url: http://opensource.org/licenses/MIT
    gpl-compatible: true
    //cdnjs.cloudflare.com/ajax/libs/selectivizr/1.0.2/selectivizr-min.js: { every_page: true, weight: -1, browsers: { IE: 'lte IE 8', '!IE': false } }

Responsive Layouts

In 2014 you cannot create a website without make it responsive so it can adapt to all devices from desktops, laptops, tablets, smartphones and anything released in the future. CSS3 media queries is the preferred choice and are made easy with breakpoint. However, not all browsers support CSS3 Media Queries - in particular, Internet Explorer 8 and under. Luckily we can include a javascript tool as a fall-back solution for older browsers.

# Min/max-width media query polyfill for IE 6-8.
  remote: https://github.com/scottjehl/Respond
  version: 1.4.2
    name: MIT
    url: https://github.com/scottjehl/Respond/blob/master/LICENSE-MIT
    gpl-compatible: true
    //cdnjs.cloudflare.com/ajax/libs/respond.js/1.4.2/respond.js: { every_page: true, weight: -1, browsers: { IE: 'lte IE 8', '!IE': false } }


Google Fonts offer hundreds of free, open-source fonts optimized for the web. They are very easy to integrate by hooking into our prius.theme which is the new drupal 8 file for all your theme functions.

 * Implements hook_css_alter().
function prius_css_alter(&$css) {
  // Add CDN Google fonts.
  $googlefonts = '//fonts.googleapis.com/css?family=Lato:400italic,600italic,70';
  $css[$googlefonts] = array(
    'data' => $googlefonts,
    'type' => 'external',
    'every_page' => TRUE,
    'media' => 'all',
    'preprocess' => FALSE,
    'group' => CSS_AGGREGATE_THEME,
    'browsers' => array('IE' => TRUE, '!IE' => TRUE),
    'weight' => 2,

Font Awesone

I love Font Awesome. Everyone loves Font Awesome. Right ? Font Awesome gives you over 400 scalable vector icons that can instantly be customised - size, color, drop shadow can be changed through CSS. Integrate them into your Drupal 8 is dead easy. We just needed to implement the hook_css_alter() in our prius.theme. Font Awesone doesn't support IE7 so we use a IE conditional stylesheets.

 * Implements hook_css_alter().
function prius_css_alter(&$css) {
  // Add CDN FontAwesome (Support from IE8).
  $fontawesome = '//netdna.bootstrapcdn.com/font-awesome/4.1.0/css/font-awesome.min.css';
  $css[$fontawesome] = array(
    'data' => $fontawesome,
    'type' => 'external',
    'every_page' => TRUE,
    'media' => 'all',
    'preprocess' => FALSE,
    'group' => CSS_AGGREGATE_THEME,
    'browsers' => array('IE' => 'gte IE 8'),
    'weight' => 1,


We use a sort of SMACSS (Scalable and Modular Architecture for CSS) to structure our sass files and make them easier to maintain.

  • partials
    • base
      • _base.scss
      • _mixins.scss
      • _variables.scss
      • _typography.scss
    • layout
      • _layout.scss
      • _grid.scss
    • component
      • _component.scss
      • _logo.scss
      • _breadcrumb.scss
    • state
      • _state.scss
      • _svg.scss
      • _scrolling.scss

Base contains the compass reset and the CSS rules which apply to elements used throughout the site like lists, headlines or tables. It will also store our variables, custom mixins and fonts definitions.

Layout contains mainly our susy grid system.

Component defines all the discrete components of the page like breadcrum, navigation or logo. Each component should be designed to exist as a standalone piece of content which could be used anywhere across your website.

State overrides your "by default" design. We use it for example to replace images by SVG if the browser support them or to amend the design if we are in a scrolling state.

Lessons learnt from our first theme

1) If you have unexpected behaviours make sure your clear the cache by:

  • Hitting the clear all cache button from the admin interface or truncate all your cache_* tables.
  • Deleting the sites/default/files/php folder.
  • Disabling and renabling your theme (Especially if you play with the YAML files).

2) You can use twig in a debug mode by setting $settings['twig_debug'] to TRUE in your settings file. Debugging markup will appear to help you to figure out which templates are used and how to override them.

3) Debugging variables in Twig templates can be tricky. But you can loop through _context to inspect all its keys and then loop through each keys etc...

 {% for key, value in _context  %}
   {{ key }}
 {% endfor %}