Bourbon Introduction

What is Bourbon?

Bourbon is thoughtbot's open-source Sass library. It's a suite of convenient utilities and helpers to help you with common tasks in Sass. thoughtbot extracted it from projects that we've done, so it solves a lot of the pain points we've experienced.

Bourbon is intentionally lightweight: for example, instead of generating vendor prefixes like -ms-border-radius, it assumes you will use autoprefixer (or autoprefixer-rails) to add prefixes. Autoprefixer is better at it than Bourbon and can generate less code.

Bourbon is part of a family of Sass libraries including Neat, Bitters and Refills. - Because the family is modular, you can choose which libraries to use based on your project's needs - Bourbon is very lightweight and gives most of the control to the developer - With a library of tools rather than predetermined CSS classes, you can craft higher quality, semantic code

Installing Bourbon

If we follow the Bourbon README:

1. Add Bourbon to your Gemfile:

  gem "bourbon"

1. Then run:

  bundle install

1. If you're not using Rails, run bourbon install.

2. Import Bourbon at the beginning of application.css.scss. All other stylesheets should be imported below Bourbon:

  // With Rails:
  @import "bourbon";
  // Without Rails:
  // @import "bourbon/bourbon";

  @import "site-header";

Bourbon Features

Below are a handful of Bourbon's features.

hide-text

This mixin hides the text within an element and is commonly used to show an image instead. For example, you might have <h1>thoughtbot</h1> but on rendering, you want thoughtbot's logo to show up in the <h1>, not the word "thoughtbot". Screen readers and Google see the text, but other users see the logo.

SCSS:

.logo {
  @include hide-text;
}

Compiled CSS:

.logo {
  overflow: hidden;
  text-indent: 101%;
  white-space: nowrap;
}

This is a great example of Bourbon being convenient. The best practices for hiding text have changed over time. This way Bourbon takes care of being up to date and you no longer have to remember the specific CSS properties to use.

size

Bourbon's size mixin can set the width and height of an element in one statement. If you pass one argument, size will use that value as the width and height. You can also pass two arguments to set separate width and height values.

SCSS:

.component {
  @include size(100px);
}

Compiled CSS:

.component {
  height: 100px;
  width: 100px;
}

margin

The margin mixin provides a quick method for targeting margins on specific sides of a box and allows you to "skip" a side by using null. Just like [the margin shorthand][shorthand] in CSS, if you provide two values it will intrpret them as the top/bottom and left/right values. Unlike CSS, the margin mixin lets you not set a value at all.

[shorthand]: https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties

SCSS:

.component {
  @include margin(20px null);
}

Compiled CSS:

.component {
  margin-bottom: 20px;
  margin-top: 20px;
  /* Since we passed `null`, there's no left/right margin set */
}

The ability to use null is valuable for preventing "accidental resets". This can happen when you use CSS shorthand (e.g. margin: 20px 0;), which always sets all values. With null values, Bourbon's margin mixin lets you set only the margins you need to set, without using longhand CSS.

position

When setting the position of an element in CSS, it's not uncommon to also need to set the top, right, bottom and/or left properties. Bourbon gives us a position mixin to accomplish all of this in one line. It behaves like the margin mixin in that we can "skip" sides by passing null.

SCSS:

.component {
  @include position(absolute, 0 1em null null);
}

Compiled CSS:

.component {
  right: 10em;
  position: absolute;
  top: 0;
}

$all-buttons and $all-text-inputs variables

Bourbon provides a few helpful variables, like $all-buttons (which is a list of all HTML button elements) and $all-text-inputs (which is a list of all text-based HTML input elements). Bourbon provides the variables but doesn't do anything with them. Like a lot of what Bourbon provides, it's a helpful tool that doesn't render any CSS out of the box. They're useful for targeting global styles and Bitters uses them to do just that.

SCSS:

#{$all-buttons} {
  background-color: #f00;
}

Compiled CSS:

button,
[type="button"],
[type="reset"],
[type="submit"] {
  background-color: #f00;
}

contrast-switch

Bourbon's contrast-switch function switches between two colors based on the lightness of a another color. It's new in Bourbon 5, and it's great for building button styles or other styles that vary with the background color.

contrast-switch takes in a background color and two text colors, and it will switch between those colors based on which one has higher contrast against the background.

contrast-switch defaults to coloring the text black or white, so a common way to call it is just with the background color: contrast-switch(blue).

SCSS:

.button {
  color: contrast-switch(blue, #222, #fff);
}

Compiled CSS:

.button {
  color: #fff;
}