WordPress – Up and Running with Grunt, Sass, Bourbon and Neat

So what is Neat? Well Neat is a semantic, lightweight, and powerful grid built on top of Bourbon and Sass. It’s ideal for most grid situations and is a great front-end CSS framework for Responsive Website Design. There are lots of frameworks to choose from when doing front-end development for WordPress, but the goal of using Neat is more of a philosophical one, which is to keep markup cleaner and less polluted.

There are many options to get up and running with Bourbon and Neat, like using Codekit and other CSS preprocessors, but today I’d like to touch on Getting Up and Running with Bourbon Neat and Grunt.

Grunt Setup

If you’re not familiar with Grunt, I’ve included a couple handy-dandy tutorials to get you started. It can be overwhelming at first, but each of these tutorials will walk you through the process to get up and running. I’ve also included a link to our wd_s theme, which you can use for an example to see how the setup is done. I really recommend checking this setup out because it’s a really good example to help clear up some issues you may come across when getting started.

• Grunt is not weird and hard
• Grunt.js Getting Started
• Smashing Magazine Up and Running Grunt
• wd_s framework

Once you’ve got Grunt running for your project, the next step is getting Bourbon and Neat setup as well. These are the initial steps for installing Bourbon and Neat. You’ll need both as they work in tandem, as Neat is reliant on Bourbon.

Source: https://github.com/thoughtbot/neat#installation

After this is done you’ll want to also double-check and add these two snippets to package.json and gruntfile.js. To some this might be obvious, but when you’re just starting out it can be a little confusing to get all this awesomeness up and running for your project.

Package.json

{"devDependencies":{"css-parse":"^2.0.0","glob":"^4.0.2","grunt":"^0.4.5","grunt-autoprefixer":"^1.0.1","grunt-combine-media-queries":"^1.0.0","grunt-contrib-clean":"^0.6.0","grunt-contrib-concat":"^0.5.0","grunt-contrib-connect":"^0.8.0","grunt-contrib-cssmin":"^0.10.0","grunt-contrib-imagemin":"^0.8.1","grunt-contrib-jshint":"^0.10.0","grunt-contrib-sass":"^0.8.1","grunt-contrib-uglify":"^0.6.0","grunt-contrib-watch":"^0.6.1","grunt-csscomb":"^3.0.0","grunt-githooks":"^0.3.0","grunt-newer":"^0.7.0","grunt-phpcs":"^0.2.3","grunt-shell":"^1.1.1","grunt-spritesmith":"^2.20.0","grunt-update-submodules":"^0.4.1","grunt-wp-i18n":"^0.4.8","load-grunt-tasks":"^0.6.0","node-bourbon":"^1.2.3","node-neat":"1.3.0"}}

Gruntfile.js

module.exports = function(grunt) {

// load all grunt tasks in package.json matching the `grunt-*` pattern
require('load-grunt-tasks')(grunt);

grunt.initConfig({
 sass: {
   dist: {
     options: {
       style: 'expanded',
       lineNumbers: true,
       loadPath: require('node-neat').includePaths,
       source map: none
     },
   files: {
    'themes/_s/style.css': 'themes/_s/sass/style.scss'
   }
 }
},

Notice here on line 12, you’ll only need to require Neat as it’s dependent on Bourbon so it’s not necessary to include Bourbon here in addition to Neat.

Lets Dig In

Alright, so if you’re still with me after all the setup, let’s dig in a little and actually start using some Neat! Because Bourbon and Neat are dependent on SASS you’ll also need to add these snippets in this order at the top of your style.scss file:

@import "bourbon";
@import "partials/grid-settings";
@import "neat";

@import "the rest of your partials below";

Grid settings is not a requirement by any means, but if you want to override the default 12 column grid you’ll want to do it here in this file. Once you’ve got things set up the way you want, you’re ready to rock and roll.

Getting Started with Neat

To get started, you’ll want to set your outermost container like so with the two elements in that row spanning the desired column widths. The outermost container will apply the max-width you’ve setup in your settings. In this example you’ll see .content is the outer-container with the primary section spanning 9 columns and the sidebar 3. Neat will automatically create the gutter based on your settings or the default settings.

// Assuming a 12 column layout
.content {
  @include outer-container;
  
  .primary-content {
    @indclue span-columns(9);
  }
  
  .sidebar-content {
    @include span-columns(3);
  }
}

It’s important to note if you have multiple rows in the same container, you’ll want to add an omega(); along with the last div of a row like the example below. Omega removes the margin from the last item and clears the row.

// Assuming a 12 column layout with multiple rows in the same container
 
.content {
  @include outer-container;
  
  .primary-content {
    @indclue span-columns(9);
  }
  
  .sidebar-content {
    @include span-columns(3);
    @include omega();
  }
  
  .primary-contnet-below {
    @include span-columns (9);
  }
  
  .sidebar-content-below {
    @include span-columns (3);
    @include omega();
  }
}

This is really just scratching the surface of the power behind running Bourbon and Neat to get you started. There are some other great examples on the neat.bourbon.io website to get you started as well.

Omega Reset

Although I’m not going to go super in-depth about using multiple columns, I highly recommend checking out Josh Fry’s article on Omega Reset. It’s fantastic and super helpful assuming you’re doing mobile first design, not to mention it’ll save you a few headaches and panic attacks!

A Few Notes and Tips

Hopefully by now you’ve can see, that when using a grid, Bourbon and Neat is lightweight, flexible and makes a lot of sense. Sometimes however even when using a grid, you’ll find that certain elements of a design require a very specific width or you have to match a PSD mockup that isn’t exactly 100% on grid. So what does one do?

Well fortunately, you can easily override some of these settings in your Sass partials. It’s nice and always ideal to use whole integers when using Neat, but it’s important to note, you don’t always have to use whole integers. While this isn’t exactly ideal, it’s good for those occasional situations that come up. If it’s going to happen a lot during your project, you may then want to consider alternative tools, like a super simple grid. Learn from me if you can, I’ve been down that road, and it doesn’t end in Rainbows and Unicorns or a Pot of Gold. Here’s an example of when you might need to do something a little different:

// Assuming a 12 column layout for special circumstances
.content {
  @include outer-container;
  
  .primary-content {
    @indclue span-columns(7.25);
  }
  
  .sidebar-content {
    @include span-columns(4.75);
  }
}

All in all Bourbon Neat is a really cool tool for development and even prototyping quick layout mockups. It’s versatility and flexibility are well supported Cross Browser, and there are some good helpers for older browsers as well if you need to support IE8 and back as well. I encourage you to check it out, take it for a spin. If you have any cool tips that you’d like to share or experiences you encountered, let us know, we’d love to hear them!

Some Additional Resources Worth Checking Out:

• Cheat Sheet: http://www.cheatography.com/claysmith/cheat-sheets/bourbon-neat/
• Read More of the Docs: http://neat.bourbon.io/
• Github: https://github.com/thoughtbot/neat