Bourbon

Bourbon is a comprehensive Sass library providing a collection of pure Sass mixins, functions, and utilities designed to enhance developer productivity when building stylesheets. It offers dependency-free CSS3 mixins, responsive design helpers, typography utilities, and color manipulation functions, all while maintaining zero visual output by default and focusing on human-readable, lightweight code.

Package Information

• Package Name: bourbon
• Package Type: npm (also available as Ruby gem)
• Language: Sass/SCSS
• Installation: npm install bourbon

Core Imports

@import "bourbon";

For Node.js/npm with sass:

@import "bourbon/core/bourbon";

For Rails with gem:

@import "bourbon";

Basic Usage

@import "bourbon";

// Use color functions
.card {
  background-color: tint(#007acc, 20%);
  border-color: shade(#007acc, 10%);
}

// Use layout mixins
.modal {
  @include position(fixed, 0);
  @include size(400px, 300px);
}

// Use typography helpers
.logo {
  @include hide-text;
  background-image: url('logo.png');
}

// Use modular scale for consistent sizing
.heading {
  font-size: modular-scale(2); // 1.5625em with default ratio
}

// Use font stacks
.body-text {
  font-family: $font-stack-system;
}

Architecture

Bourbon is organized into several key categories:

• Configuration System: Global settings map ($bourbon) for customizing library behavior
• Color Functions: Pure functions for color manipulation (tint, shade, contrast-switch)
• Layout & Positioning: Mixins for common CSS positioning and sizing patterns
• Typography & Display: Font-face generation, text utilities, and accessibility helpers
• Border Utilities: Comprehensive border styling mixins with directional control
• Variables & Constants: Pre-defined values for font stacks, timing functions, and design scales
• Utility Functions: Mathematical and string operations (modular-scale, strip-unit)
• Legacy Support: Clearfix and vendor prefixing for older browser compatibility

Configuration

// Global configuration map (optional)
$bourbon: (
  "modular-scale-ratio": 1.25,
  "modular-scale-base": 1rem,
  "global-font-file-formats": ("woff2", "woff"),
  "rails-asset-pipeline": false,
  "contrast-switch-dark-color": #000,
  "contrast-switch-light-color": #fff
);

Configuration must be set before importing Bourbon.

Capabilities

Color Functions

Color manipulation functions for creating consistent color schemes with proper contrast handling.

@function tint($color, $percent): color;
@function shade($color, $percent): color;
@function contrast-switch($base-color, $dark-color, $light-color): color;

Color Functions

Layout & Positioning

Mixins for positioning elements, setting dimensions, and managing spacing with support for null values and CSS shorthand.

@mixin position($position, $box-edge-values);
@mixin size($width, $height);
@mixin margin($values);
@mixin padding($values);

Layout & Positioning

Typography & Display

Font loading, text utilities, and accessibility helpers for consistent typography and visual presentation.

@mixin font-face($font-family, $file-path, $file-formats, $asset-pipeline);
@mixin ellipsis($width, $display);
@mixin hide-text;
@mixin hide-visually($toggle);
@mixin overflow-wrap($wrap);

Typography & Display

Border Utilities

Comprehensive border styling with individual edge control and shorthand support.

@mixin border-color($values);
@mixin border-style($values);
@mixin border-width($values);
@mixin border-top-radius($radii);
@mixin border-right-radius($radii);
@mixin border-bottom-radius($radii);
@mixin border-left-radius($radii);

Border Utilities

Variables & Constants

Pre-defined values for consistent design including font stacks, CSS timing functions, modular scale ratios, and form element selectors.

// Example variables
$font-stack-system: (system-ui, -apple-system, ...);
$major-third: 1.25;
$ease-in-out-cubic: cubic-bezier(0.645, 0.045, 0.355, 1);
$all-text-inputs: ('input[type="email"]', 'input[type="text"]', ...);

Variables & Constants

Utilities

Mathematical functions, utility mixins, and helper functions for common Sass operations.

@function modular-scale($increment, $value, $ratio): number;
@function strip-unit($value): number;
@mixin clearfix;
@mixin triangle($direction, $width, $height, $color);
@mixin prefixer($property, $value, $prefixes);
@mixin value-prefixer($property, $value, $prefixes);

Utilities

Browser Support

Bourbon supports Internet Explorer 11+ and the latest versions of Chrome, Firefox, Safari, and Edge.

Error Handling

Bourbon functions and mixins include validation for their arguments and will throw Sass compilation errors for invalid inputs:

• Color functions validate that color arguments are valid CSS colors
• Size and length functions validate that numeric arguments have appropriate units
• Directional mixins validate that shorthand values are properly formatted

These errors appear during Sass compilation and help catch mistakes early in the development process.