Documentation

border-color

Provides a concise, one-line method for setting border-color on specific edges of a box. Use a null value to “skip” edges of the box with standard CSS shorthand.

Arguments

Name Type Description
$values list

List of colors; accepts CSS shorthand.

Example 

.element {
  @include border-color(#a60b55 #76cd9c null #e8ae1a);
}

// CSS Output
.element {
  border-left-color: #e8ae1a;
  border-right-color: #76cd9c;
  border-top-color: #a60b55;
}

border-top-radius

Provides a concise, one-line method for setting border-radius on both the top-left and top-right of a box.

Arguments

Name Type Description
$radii number (with unit) —

Example 

.element {
  @include border-top-radius(4px);
}

// CSS Output
.element {
  border-top-left-radius: 4px;
  border-top-right-radius: 4px;
}

border-right-radius

Provides a concise, one-line method for setting border-radius on both the top-right and bottom-right of a box.

Arguments

Name Type Description
$radii number (with unit) —

Example 

.element {
  @include border-right-radius(3px);
}

// CSS Output
.element {
  border-bottom-right-radius: 3px;
  border-top-right-radius: 3px;
}

border-bottom-radius

Provides a concise, one-line method for setting border-radius on both the bottom-left and bottom-right of a box.

Arguments

Name Type Description
$radii number (with unit) —

Example 

.element {
  @include border-bottom-radius(2px);
}

// CSS Output
.element {
  border-bottom-left-radius: 2px;
  border-bottom-right-radius: 2px;
}

border-left-radius

Provides a concise, one-line method for setting border-radius on both the top-left and bottom-left of a box.

Arguments

Name Type Description
$radii number (with unit) —

Example 

.element {
  @include border-left-radius(1px);
}

// CSS Output
.element {
  border-bottom-left-radius: 1px;
  border-top-left-radius: 1px;
}

border-style

Provides a concise, one-line method for setting border-style on specific edges of a box. Use a null value to “skip” edges of the box with standard CSS shorthand.

Arguments

Name Type Description
$values list

List of border styles; accepts CSS shorthand.

Example 

.element {
  @include border-style(dashed null solid);
}

// CSS Output
.element {
  border-bottom-style: solid;
  border-top-style: dashed;
}

border-width

Provides a concise, one-line method for setting border-width on specific edges of a box. Use a null value to “skip” edges of the box with standard CSS shorthand.

Arguments

Name Type Description
$values list

List of border widths; accepts CSS shorthand.

Example 

.element {
  @include border-width(1em null 20px);
}

// CSS Output
.element {
  border-bottom-width: 20px;
  border-top-width: 1em;
}

all-buttons

A list of all HTML button elements. Please note that you must interpolate the variable (#{}) to use it as a selector.

Example 

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

// CSS Output
button,
[type='button'],
[type='reset'],
[type='submit'] {
  background-color: #f00;
}

all-buttons-active

A list of all HTML button elements with the :active pseudo-class applied. Please note that you must interpolate the variable (#{}) to use it as a selector.

Example 

#{$all-buttons-active} {
  background-color: #00f;
}

// CSS Output
button:active,
[type='button']:active,
[type='reset']:active,
[type='submit']:active {
  background-color: #00f;
}

all-buttons-focus

A list of all HTML button elements with the :focus pseudo-class applied. Please note that you must interpolate the variable (#{}) to use it as a selector.

Example 

#{$all-buttons-focus} {
  background-color: #0f0;
}

// CSS Output
button:focus,
[type='button']:focus,
[type='reset']:focus,
[type='submit']:focus {
  background-color: #0f0;
}

all-buttons-hover

A list of all HTML button elements with the :hover pseudo-class applied. Please note that you must interpolate the variable (#{}) to use it as a selector.

Example 

#{$all-buttons-hover} {
  background-color: #0f0;
}

// CSS Output
button:hover,
[type='button']:hover,
[type='reset']:hover,
[type='submit']:hover {
  background-color: #0f0;
}

clearfix

Provides an easy way to include a clearfix for containing floats.

Example 

.element {
  @include clearfix;
}

// CSS Output
.element::after {
  clear: both;
  content: "";
  display: block;
}

contrast-switch

Switches between two colors based on the contrast to another color. It’s like a ternary operator for color contrast and can be useful for building a button system.

The calculation of the contrast ratio is based on the WCAG 2.0 specification. However, we cannot guarantee full compliance, though all of our manual testing passed.

Arguments

Name Type Description
$base-color color

The color to evaluate lightness against.
$dark-color (#000) color

The color to be output when $base-color is light. Can also be set globally using the contrast-switch-dark-color key in the Bourbon settings.
$light-color (#fff) color

The color to be output when $base-color is dark. Can also be set globally using the contrast-switch-light-color key in the Bourbon settings.

Examples 

.element {
  color: contrast-switch(#bae6e6);
}

// CSS Output
.element {
  color: #000;
}
.element {
  $button-color: #2d72d9;
  background-color: $button-color;
  color: contrast-switch($button-color, #222, #eee);
}

// CSS Output
.element {
  background-color: #2d72d9;
  color: #eee;
}

ellipsis

Truncates text and adds an ellipsis to represent overflow.

Arguments

Name Type Description
$width (100%) number

The max-width for the string to respect before being truncated.
$display (inline-block) string

Sets the display-value of the element.

Example 

.element {
  @include ellipsis;
}

// CSS Output
.element {
  display: inline-block;
  max-width: 100%;
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
  word-wrap: normal;
}

font-face

Generates an @font-face declaration. You can choose the specific file formats you need to output; the mixin supports woff2 and woff. The mixin also supports usage with the Rails Asset Pipeline, which you can enable per use, or globally in the $bourbon() settings.

Content

This mixin allows you to pass in a block of styles for placement within the styles included by the mixin.

Any additional CSS properties that are included in the @include directive will be output within the @font-face declaration, e.g. you can pass in font-weight, font-style and/or unicode-range.

Arguments

Name Type Description
$font-family string —
$file-path string —
$file-formats (("woff2", "woff")) string | list

List of the font file formats to include. Can also be set globally using the global-font-file-formats key in the Bourbon settings.
$asset-pipeline (false) boolean

Set to true if you’re using the Rails Asset Pipeline (place the fonts in app/assets/fonts/). Can also be set globally using the rails-asset-pipeline key in the Bourbon settings.

Example 

@include font-face(
  "source-sans-pro",
  "fonts/source-sans-pro-regular",
  ("woff2", "woff")
) {
  font-style: normal;
  font-weight: 400;
}

// CSS Output
@font-face {
  font-family: "source-sans-pro";
  src: url("fonts/source-sans-pro-regular.woff2") format("woff2"),
       url("fonts/source-sans-pro-regular.woff") format("woff");
  font-style: normal;
  font-weight: 400;
}

font-stack-helvetica

A variable that outputs a Helvetica font stack.

Example 

.element {
  font-family: $font-stack-helvetica;
}

// CSS Output
.element {
  font-family: "Helvetica Neue", "Helvetica", "Arial", sans-serif;
}

font-stack-lucida-grande

A variable that outputs a Lucida Grande font stack.

Example 

.element {
  font-family: $font-stack-lucida-grande;
}

// CSS Output
.element {
  font-family: "Lucida Grande", "Lucida Sans Unicode", "Geneva", "Verdana", sans-serif;
}

font-stack-verdana

A variable that outputs a Verdana font stack.

Example 

.element {
  font-family: $font-stack-verdana;
}

// CSS Output
.element {
  font-family: "Verdana", "Geneva", sans-serif;
}

font-stack-system

A variable that outputs a system font stack.

Example 

.element {
  font-family: $font-stack-system;
}

// CSS Output
.element {
  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Avenir Next", "Avenir", "Segoe UI", "Lucida Grande", "Helvetica Neue", "Helvetica", "Fira Sans", "Roboto", "Noto", "Droid Sans", "Cantarell", "Oxygen", "Ubuntu", "Franklin Gothic Medium", "Century Gothic", "Liberation Sans", sans-serif;
}

font-stack-garamond

A variable that outputs a Garamond font stack.

Example 

.element {
  font-family: $font-stack-garamond;
}

// CSS Output
.element {
  font-family: "Garamond", "Baskerville", "Baskerville Old Face", "Hoefler Text", "Times New Roman", serif;
}

font-stack-georgia

A variable that outputs a Georgia font stack.

Example 

.element {
  font-family: $font-stack-georgia;
}

// CSS Output
.element {
  font-family: "Georgia", "Times", "Times New Roman", serif;
}

font-stack-hoefler-text

A variable that outputs a Hoefler Text font stack.

Example 

.element {
  font-family: $font-stack-hoefler-text;
}

// CSS Output
.element {
  font-family: "Hoefler Text", "Baskerville Old Face", "Garamond", "Times New Roman", serif;
}

font-stack-consolas

A variable that outputs a Consolas font stack.

Example 

.element {
  font-family: $font-stack-consolas;
}

// CSS Output
.element {
  font-family: "Consolas", "monaco", monospace;
}

font-stack-courier-new

A variable that outputs a Courier New font stack.

Example 

.element {
  font-family: $font-stack-courier-new;
}

// CSS Output
.element {
  font-family: "Courier New", "Courier", "Lucida Sans Typewriter", "Lucida Typewriter", monospace;
}

font-stack-monaco

A variable that outputs a Monaco font stack.

Example 

.element {
  font-family: $font-stack-monaco;
}

// CSS Output
.element {
  font-family: "Monaco", "Consolas", "Lucida Console", monospace;
}

hide-text

Hides the text in an element, commonly used to show an image instead. Some elements will need block-level styles applied.

Example 

.element {
  @include hide-text;
}

// CSS Output
.element {
  overflow: hidden;
  text-indent: 101%;
  white-space: nowrap;
}

hide-visually

Hides an element visually while still allowing the content to be accessible to assistive technology, e.g. screen readers. Passing unhide will reverse the affects of the hiding, which is handy for showing the element on focus, for example.

Arguments

Name Type Description
$toggle (hide) string

Accepts hide or unhide. unhide reverses the affects of hide.

Example 

.element {
  @include hide-visually;

  &:active,
  &:focus {
    @include hide-visually("unhide");
  }
}

// CSS Output
.element {
  border: 0;
  clip: rect(1px, 1px, 1px, 1px);
  clip-path: inset(100%);
  height: 1px;
  overflow: hidden;
  padding: 0;
  position: absolute;
  width: 1px;
}

.hide-visually:active,
.hide-visually:focus {
  clip: auto;
  clip-path: none;
  height: auto;
  overflow: visible;
  position: static;
  width: auto;
}

margin

Provides a concise, one-line method for setting margin on specific edges of a box. Use a null value to “skip” edges of the box with standard CSS shorthand.

Arguments

Name Type Description
$values list

List of margin values; accepts CSS shorthand.

Examples 

.element {
  @include margin(null auto);
}

// CSS Output
.element {
  margin-left: auto;
  margin-right: auto;
}
.element {
  @include margin(10px 3em 20vh null);
}

// CSS Output
.element {
  margin-bottom: 20vh;
  margin-right: 3em;
  margin-top: 10px;
}

modular-scale

Increments up or down a defined scale and returns an adjusted value. This helps establish consistent measurements and spacial relationships throughout your project. We provide a list of commonly used scales as pre-defined variables.

Arguments

Name Type Description
$increment number (unitless)

How many steps to increment up or down the scale.
$value (1em) number (with unit) | list

The base value the scale starts at. Can also be set globally using the modular-scale-base key in the Bourbon settings.
$ratio (1.25) number (unitless)

The ratio the scale is built on. Can also be set globally using the modular-scale-ratio key in the Bourbon settings.

Examples 

.element {
  font-size: modular-scale(2);
}

// CSS Output
.element {
  font-size: 1.5625em;
}
.element {
  margin-right: modular-scale(3, 2em);
}

// CSS Output
.element {
  margin-right: 3.90625em;
}
.element {
  font-size: modular-scale(3, 1em 1.6em, $major-seventh);
}

// CSS Output
.element {
  font-size: 3em;
}
// Globally change the base ratio
$bourbon: (
  "modular-scale-ratio": 1.2,
);

.element {
  font-size: modular-scale(3);
}

// CSS Output
.element {
  font-size: 1.728em;
}

overflow-wrap

Outputs the overflow-wrap property and its legacy name word-wrap to support browsers that do not yet use overflow-wrap.

Arguments

Name Type Description
$wrap (break-word) string

Accepted CSS values are normal, break-word, inherit, initial, or unset.

Example 

.wrapper {
  @include overflow-wrap;
}

// CSS Output
.wrapper {
  word-wrap: break-word;
  overflow-wrap: break-word;
}

padding

Provides a concise method for targeting padding on specific sides of a box. Use a null value to “skip” a side.

Arguments

Name Type Description
$values list

List of padding values; accepts CSS shorthand.

Examples 

.element-one {
  @include padding(null 1rem);
}

// CSS Output
.element-one {
  padding-left: 1rem;
  padding-right: 1rem;
}
.element-two {
  @include padding(10vh null 10px 5%);
}

// CSS Output
.element-two {
  padding-bottom: 10px;
  padding-left: 5%;
  padding-top: 10vh;
}

position

Provides a concise, one-line method for setting an element’s positioning properties: position, top, right, bottom and left. Use a null value to “skip” an edge of the box.

Arguments

Name Type Description
$position string

A CSS position value.
$box-edge-values list

List of lengths; accepts CSS shorthand.

Examples 

.element {
  @include position(relative, 0 null null 10em);
}

// CSS Output
.element {
  left: 10em;
  position: relative;
  top: 0;
}
.element {
  @include position(absolute, 0);
}

// CSS Output
.element {
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
}

prefixer

Generates vendor prefixes.

Arguments

Name Type Description
$property string

Property to prefix.
$value string

Value to use.
$prefixes list

Vendor prefixes to output.

Example 

.element {
  @include prefixer(appearance, none, ("webkit", "moz"));
}

// CSS Output
.element {
  -webkit-appearance: none;
  -moz-appearance: none;
  appearance: none;
}

shade

Mixes a color with black.

Arguments

Name Type Description
$color color —
$percent number (percentage)

The amount of black to be mixed in.

Example 

.element {
  background-color: shade(#ffbb52, 60%);
}

// CSS Output
.element {
  background-color: #664a20;
}

size

Sets the width and height of the element in one statement.

Arguments

Name Type Description
$width number (with unit) | string —
$height ($width) number (with unit) | string —

Examples 

.first-element {
  @include size(2em);
}

// CSS Output
.first-element {
  width: 2em;
  height: 2em;
}
.second-element {
  @include size(auto, 10em);
}

// CSS Output
.second-element {
  width: auto;
  height: 10em;
}

strip-unit

Strips the unit from a number.

Arguments

Name Type Description
$value number —

Example 

$dimension: strip-unit(10em);

// Output
$dimension: 10;

all-text-inputs

A list of all text-based HTML inputs. Please note that you must interpolate the variable (#{}) to use it as a selector.

Example 

#{$all-text-inputs} {
  border: 1px solid #ccc;
}

// CSS Output
[type='color'],
[type='date'],
[type='datetime'],
[type='datetime-local'],
[type='email'],
[type='month'],
[type='number'],
[type='password'],
[type='search'],
[type='tel'],
[type='text'],
[type='time'],
[type='url'],
[type='week'],
input:not([type]),
textarea {
  border: 1px solid #ccc;
}

all-text-inputs-active

A list of all text-based HTML inputs with the :active pseudo-class applied. Please note that you must interpolate the variable (#{}) to use it as a selector.

Example 

#{$all-text-inputs-active} {
  border: 1px solid #aaa;
}

// CSS Output
[type='color']:active,
[type='date']:active,
[type='datetime']:active,
[type='datetime-local']:active,
[type='email']:active,
[type='month']:active,
[type='number']:active,
[type='password']:active,
[type='search']:active,
[type='tel']:active,
[type='text']:active,
[type='time']:active,
[type='url']:active,
[type='week']:active,
input:not([type]):active,
textarea:active {
  border: 1px solid #aaa;
}

all-text-inputs-focus

A list of all text-based HTML inputs with the :focus pseudo-class applied. Please note that you must interpolate the variable (#{}) to use it as a selector.

Example 

#{$all-text-inputs-focus} {
  border: 1px solid #1565c0;
}

// CSS Output
[type='color']:focus,
[type='date']:focus,
[type='datetime']:focus,
[type='datetime-local']:focus,
[type='email']:focus,
[type='month']:focus,
[type='number']:focus,
[type='password']:focus,
[type='search']:focus,
[type='tel']:focus,
[type='text']:focus,
[type='time']:focus,
[type='url']:focus,
[type='week']:focus,
input:not([type]):focus,
textarea:focus {
  border: 1px solid #1565c0;
}

all-text-inputs-hover

A list of all text-based HTML inputs with the :hover pseudo-class applied. Please note that you must interpolate the variable (#{}) to use it as a selector.

Example 

#{$all-text-inputs-hover} {
  border: 1px solid #aaa;
}

// CSS Output
[type='color']:hover,
[type='date']:hover,
[type='datetime']:hover,
[type='datetime-local']:hover,
[type='email']:hover,
[type='month']:hover,
[type='number']:hover,
[type='password']:hover,
[type='search']:hover,
[type='tel']:hover,
[type='text']:hover,
[type='time']:hover,
[type='url']:hover,
[type='week']:hover,
input:not([type]):hover,
textarea:hover {
  border: 1px solid #aaa;
}

all-text-inputs-invalid

A list of all text-based HTML inputs with the :invalid pseudo-class applied. Please note that you must interpolate the variable (#{}) to use it as a selector.

Example 

#{$all-text-inputs-invalid} {
  border: 1px solid #00f;
}

// CSS Output
[type='color']:invalid,
[type='date']:invalid,
[type='datetime']:invalid,
[type='datetime-local']:invalid,
[type='email']:invalid,
[type='month']:invalid,
[type='number']:invalid,
[type='password']:invalid,
[type='search']:invalid,
[type='tel']:invalid,
[type='text']:invalid,
[type='time']:invalid,
[type='url']:invalid,
[type='week']:invalid,
input:not([type]):invalid,
textarea:invalid {
  border: 1px solid #00f;
}

tint

Mixes a color with white.

Arguments

Name Type Description
$color color —
$percent number (percentage)

The amount of white to be mixed in.

Example 

.element {
  background-color: tint(#6ecaa6, 40%);
}

// CSS Output
.element {
  background-color: #a8dfc9;
}

triangle

Generates a triangle pointing in a specified direction.

Arguments

Name Type Description
$direction string

The direction the triangle should point. Accepts up, up-right, right, down-right, down, down-left, left or up-left.
$width number (with unit)

Width of the triangle.
$height number (with unit)

Height of the triangle.
$color color

Color of the triangle.

Example 

.element {
  &::before {
    @include triangle("up", 2rem, 1rem, #b25c9c);
    content: "";
  }
}

// CSS Output
.element::before {
  border-style: solid;
  height: 0;
  width: 0;
  border-color: transparent transparent #b25c9c;
  border-width: 0 1rem 1rem;
  content: "";
}

value-prefixer

Generates vendor prefixes for values.

Arguments

Name Type Description
$property string

Property to use.
$value string

Value to prefix.
$prefixes list

Vendor prefixes to output.

Example 

.element {
  @include value-prefixer(cursor, grab, ("webkit", "moz"));
}

// CSS Output
.element {
  cursor: -webkit-grab;
  cursor: -moz-grab;
  cursor: grab;
}

Settings

Global Bourbon settings.

Properties

Name Type Description
contrast-switch-dark-color color

Global dark color for the contrast-switch function.
contrast-switch-light-color color

Global light color for the contrast-switch function.
global-font-file-formats list

Global font file formats for the font-face mixin.
modular-scale-base number (with unit)

Global base value for the modular-scale function.
modular-scale-ratio number (unitless)

Global base ratio for the modular-scale function.
rails-asset-pipeline boolean

Set this to true when using the Rails Asset Pipeline and Bourbon will write asset paths using sass-rails’ asset helpers.

Example 

$bourbon: (
  "contrast-switch-dark-color": #000,
  "contrast-switch-light-color": #fff,
  "global-font-file-formats": ("woff2", "woff"),
  "modular-scale-base": 1em,
  "modular-scale-ratio": $major-third,
  "rails-asset-pipeline": false,
);