Bitters and Refills

Bitters are our scaffold styles for a new project. Our Rails template, Suspenders, comes with Bitters out of the box so that you start with a nice Sass project structure and some good global styles.

What is Bitters?

Bitters is different from Bourbon and Neat in that it is not a library, but a project scaffold. Rather than providing mixins and functions, Bitters provides a basic set of Sass variables, default element styles and project structure. Unlike Bourbon and Neat, Bitters should be edited: set your own brand colors, change your global form styles, and so on to fit your project. Bitters is a starting point.

Installing Bitters

1. Install the Bitters gem using the RubyGems package manager:

  gem install bitters

1. Install the Bitters library into the current directory by running the following command at the command-line. If you’re using Ruby on Rails, run the command in the app/assets/stylesheets directory:

  bitters install

A base directory will be generated which contains all of the Bitters files.

1. Import Bitters after Bourbon (and Neat, if you're using it) in your application.css.scss or main manifest file. All additional stylesheets should be imported below Bitters.

  @import "bourbon";
  @import "neat"; // if using Neat
  @import "base/base";

  // other stylesheets go here

More on Bitters

Note that Bitters should not go in your Gemfile: once Bitters has generated the base directory, it's done. There's also no expectation that you keep up to date with Bitters, or re-run bitters install as we release new Bitters versions.

Bitters doesn't replace a CSS reset or normalize file, it builds from it. A reset is best for cross-browser inconsistencies with default styles; Bitters on the other hand is for a more pleasant default style that will work well for application design.

• Bitters should live in your project’s root Sass directory and should be modified and extended it to meet your design and brand needs
• Although we encourage you to edit the Bitters files, the /base directory should be limited to styling base HTML elements
  • Think <p> & <a> tags, not styles with classes or more complex selectors

Variables

Bitters cleans up fonts (it uses a sans-serif by default) and cleans up global styles like form elements and tables. A lot of that is controlled by variables.

The base/_variables.scss file houses all variables that are used in more than one file in your site. Variable names in Bitters that are used outside of the variables file start with $base to indicate that they are the most basic variables.

Variables give you a way to tweak your application's styles without having to edit in more than one place. For example, by using variables plus mixins like contrast-switch, you can change a button's base color from blue to green and have all the other styles mostly fall into place.

Through a project's life, the variables file is by far the most edited Bitters file. It is a great practice to use variables for any CSS values (margin/padding sizes, colors, borders, transitions, etc) that you're reusing and to keep all of your variables in the variables file.

Typography

Bitters is built for user interfaces. In user interfaces, the visual hierarchy isn't necessarily established by font size; it can instead be established by having lots of different elements on the page like sidebars and buttons. Because of this, headings are all set to the same font size. This is great for application development, when you want to style the headings with classes and want to use them independent of their default styles. This also means headings don't take up valuable screen real estate by defaults. When designing for a blog or site with a lot of written content, it's best to update your headings to have a hierarchy without classes.

All type is based on $base-font-size which is set to 1em (16px) by default. The spacing around type is based on $base-line-height to keep a semi-baseline grid. All sizes are scaled up or down by a factor of 0.25.

This maintains a nice rhythm throughout your site.

Refills

Bourbon and Neat provide foundational toolkits while Bitters goes a little farther and gives you base styles to customize. The last piece is Refills, which is a library of pre-built components and patterns built with Bourbon and Neat. The available refills include accordions, tabbed navigation, footers, font stacks, and more.

Each refill is independent of the others and is only dependent on Bourbon and Neat. (Refills that require JavaScript also depend on jQuery.) Refills also avoid CSS nesting more than two levels deep and keep styling to a minimum.

Just like Bitters, Refills components are meant to be generated once and then customized for your application. Each component comes with the markup, styles and any JavaScript needed for it to function properly. The components are like Bootstrap components, but much easier to customize. Many of them are built with their own set of variables that can change many of commonly customized aspects of each refill.