Bourbon

This post is not about a barrel-aged distilled spirit made primarily from corn. Instead, it is about a Sass mixin library. To add Bourbon to your web project, visit the Bourbon GitHub repo and take a look at the requirements.

The first requirement is obviously Sass, since this is a mixin library for it. As of this post, the latest Bourbon requires Sass 3.3+. To install or update Sass you will need to have Ruby installed. Ruby comes pre-installed on OS X. For Windows, you can use the RubyInstaller for Windows. When I set this up last year, I used the Ruby 1.9.3 installers. These next step are performed using a CLI. Git for Windows provides a BASH emulation that you can use instead of the Command Prompt.

Sass check / update

# version check
sass --v

Sass 3.2.12 (Media Mark)

# update
gem update sass

Updating installed gems
Updating sass
Fetching: sass-3.4.5.gem (100%)
Successfully installed sass-3.4.5
Gems updated: sass
Installing ri documentation for sass-3.4.5...
Installing RDoc documentation for sass-3.4.5...

Install Bourbon

Option 1

The installation as documented at the bourbon repo is pretty straight forward.

# Bourbon gem install
gem install bourbon

Fetching: thor-0.19.1.gem (100%)
Fetching: bourbon-4.0.2.gem (100%)
Successfully installed thor-0.19.1
Successfully installed bourbon-4.0.2
2 gems installed
Installing ri documentation for thor-0.19.1...
Installing ri documentation for bourbon-4.0.2...
Installing RDoc documentation for thor-0.19.1...
Installing RDoc documentation for bourbon-4.0.2...

# change to your project directory
# e.g., cd ~/mywebsite
# install Bourbon into your project
bourbon install

Bourbon files installed to bourbon/
Option 2

A good alternative is to use Bower to install Bourbon and manage packages for your project. You will need to have the Node Package Manger (NPM) which is bundled with Node.js. If you have not done so already, install Node.js. Then, use the NPM to install Bower

# global bower install
npm install -g bower

Next, using bower init, generate a bower.json file for your project. You will be prompted for answers to generate the file. Answering each is up to you, accept the defaults by selecting enter. After the bower.json file is created in your project, install Bourbon using bower install –save bourbon:

# change to your project directory
# e.g., cd ~/mywebsite
bower init

? name: BourbonTutorial
? version: 0.0.1
? description:
? main file:
? what types of modules does this package expose?:
? keywords:
? authors: jimfrenette <jim@jimfrenette.com>
? license: MIT
? homepage:
? set currently installed components as dependencies?: Yes
? add commonly ignored files to ignore list?: Yes
? would you like to mark this package as private which prevents it from being accidentally published to the registry?: No

{
  name: 'BourbonTutorial',
  version: '0.0.1',
  authors: [
    'jimfrenette '
  ],
  license: 'MIT',
  ignore: [
    '**/.*',
    'node_modules',
    'bower_components',
    'test',
    'tests'
  ]
}

? Looks good?: Yes

# install Bourbon into your project using Bower,
# this command installs the package and the --save option
# adds the dependency to the bower.json file

bower install --save bourbon

bower cached        git://github.com/thoughtbot/bourbon.git#4.0.2
bower validate      4.0.2 against git://github.com/thoughtbot/bourbon.git#*
bower install       bourbon#4.0.2

bourbon#4.0.2 bower_components\bourbon

Using Bourbon

Now we can create a Sass file and test drive some Bourbon mixins. Create a folder named sass in your web project root. And in that folder create a main.scss file with the code/text editor of your choice. Add the following Sass code to your new main.scss file and save it. NOTE: if you used option 1 to install Bourbon, adjust your import path as needed since /bower_components unavailable.

main.scss
@import "../bower_components/bourbon/dist/_bourbon.scss";

button {
    @include button(shiny, #ff0000);
}

Next, create a folder name css for you compiled sass output. Your directory structure should now look something like this depending on which Bourbon install option you used.

option 1
# | bourbon/
# | css/
# | sass/
#     | -- main.scss

option 2
# | bower_components/
#     | -- bourbon/
# | css/
# | sass/
#     | -- main.scss
# | bower.json
Setup sass to compile main.scss automatically

From within your projects sass folder, execute the sass watch command. Whenever your main.scss file is saved, the respective main.css will be written with all of the applicable browser extensions, reusable properties, etc..

# change to your sass folder in your project directory
# e.g., cd ~/mywebsite/sass

sass --watch  main.scss:../css/main.css

>>> Sass is watching for changes. Press Ctrl-C to stop.
←[32m      write ../css/main.css
←[0m←[32m      write ../css/main.css.map
←[0m

Here is what your /css/main.css file should look like after the Sass compile.

button {
  border: 1px solid #8a0000;
  border-bottom: 1px solid #810000;
  border-radius: 5px;
  box-shadow: inset 0 1px 0 0 #ff1d0c;
  color: white;
  display: inline-block;
  font-size: inherit;
  font-weight: bold;
  background-color: #ff0000;
  background-image: -webkit-linear-gradient(top, #ff0000 0%, #c70000 50%, #a90000 50%, #b00000 100%);
  background-image: linear-gradient(to bottom,#ff0000 0%, #c70000 50%, #a90000 50%, #b00000 100%);
  padding: 7px 18px;
  text-align: center;
  text-decoration: none;
  text-shadow: 0 -1px 1px #730000; }
  button:hover:not(:disabled) {
    cursor: pointer;
    background-color: #f20000;
    background-image: -webkit-linear-gradient(top, #f20000 0%, #bd0000 50%, #a20000 50%, #a90000 100%);
    background-image: linear-gradient(to bottom,#f20000 0%, #bd0000 50%, #a20000 50%, #a90000 100%); }
  button:active:not(:disabled), button:focus:not(:disabled) {
    box-shadow: inset 0 0 20px 0 #900000; }
  button:disabled {
    opacity: 0.5;
    cursor: not-allowed; }

/*# sourceMappingURL=main.css.map */

This is just the tip of the iceberg. With Sass, you can develop modular, reusable styles in small chunks to help make your CSS DRY and organized.

Bourbon Neat with Bitters

Neat is a lightweight semantic grid framework for Sass and Bourbon. Bitters is a set of Sass styles, variables and structure for Bourbon projects.

Going to change gears a little here and use Grunt to handle the watch & compile task for the Sass (.scss) files. Therefore, create this package.json file for NPM in the project root.

package.json
{
  "name": "bourbon-tutorial",
  "version": "0.1.0",
  "devDependencies": {
    "grunt": "~0.4.5",
    "grunt-contrib-compass": "~1.0.1",
    "grunt-contrib-watch": "~0.6.1"
  }
}

Using Bower install Option 2, your file structure should look like this:

# option 2
# | bower_components/
#     | -- bourbon/
# | css/
# | sass/
#     | -- main.scss
# | bower.json
# | package.json

From the project root directory, run the NPM install which will add the grunt node modules to the project specified in package.json

# install node modules
npm install

Install Neat and Bitters

# install neat using Bower,
# this command installs the package and the --save option
# adds the dependency to the bower.json file

bower install --save neat

# install bitters
gem install bitters

# add the library to the project,
# change to the sass directory,
# e.g., cd sass
bitters install

A base directory will be created in /sass containing the Bitters library. Detailed instructions are available here.

Create Grunt config

A Grunt configuration file is needed to run the watch and compile tasks. Create this gruntfile.js in the project root.

gruntfile.js
module.exports = function(grunt) {
  'use strict';
  // Project configuration.
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    compass: {
      dist: {
        // these options will override (or extend) config.rb settings.
        options: {
          cssDir: 'css/',
          sassDir: 'sass/',
          outputStyle: 'compressed'
        }
      }
    },
    watch: {
      css: {
        files: '**/*.scss',
        tasks: ['compass']
      }
    }
  });
  // Load the plugins.
  grunt.loadNpmTasks('grunt-contrib-compass');
  grunt.loadNpmTasks('grunt-contrib-watch');
  // Default task(s).
  grunt.registerTask('default', ['watch']);
};

Run grunt

grunt

Running "watch" task
Waiting...

Step 2

This tutorial is not using Ruby on Rails, so edit sass/base/_grid-settings.scss changing the import path as needed for neat-helpers.

_grid-settings.scss
//not in Rails
@import "../../bower_components/neat/app/assets/stylesheets/neat-helpers";

Edit sass/main.scss to import Bitters base/base and Neat. Neat is imported after Bitters.

main.scss
@import "../bower_components/bourbon/dist/_bourbon.scss";
@import "base/base";
@import "../bower_components/neat/app/assets/stylesheets/neat";

button {
    @include button(shiny, #ff0000);
}

UPDATE - Bourbon 4.1 path changes **

main.scss
// note changes to path in Bourbon 4.1
@import "../bower_components/bourbon/app/assets/stylesheets/_bourbon.scss";

** Bourbon 4.1.0 released on December 30, 2014 For Bower users, the Bourbon’s directory structure has been changed. Instead of a dist directory, which was just a duplicate of the entire Bourbon library for Bower to use, now point Bower to app/assets/stylesheets.

Bitters is a scaffold of scss files to get you started, add to or edit them as needed. Since we are using Neat, uncomment the grid-settings import in base/_base.scss:

_base.scss
// Neat Settings -- uncomment if using Neat -- must be imported before Neat
@import "grid-settings";

After saving sass/main.scss, per the running grunt tasks the terminal output should indicate that css/main.css has been written. css/main.css should be updated to contain all of the base styles from the bitters import.

>> File "sass\main.scss" changed.
Running "compass:dist" (compass) task
    write css/main.css (0.875s)

Done, without errors.
Source Code

Resources

comments powered by Disqus