bourbon 5.0.0.beta.6 → 5.0.0.beta.7

data/core/bourbon/library/_border-radius.scss

@@ -1,7 +1,7 @@
 @charset "UTF-8";
 
-/// Provides a shorthand syntax to add `border-radius` to both the top-left and
-/// top-right of an element.
+/// Provides a concise, one-line method for setting `border-radius` on both the
+/// top-left and top-right of a box.
 ///
 /// @argument {number (with unit)} $radii
 ///
@@ -10,7 +10,7 @@
 ///     @include border-top-radius(4px);
 ///   }
 ///
-/// @example css
+///   // CSS Output
 ///   .element {
 ///     border-top-left-radius: 4px;
 ///     border-top-right-radius: 4px;
@@ -21,8 +21,8 @@
   border-top-right-radius: $radii;
 }
 
-/// Provides a shorthand syntax to add `border-radius` to both the top-right and
-/// bottom-right of an element.
+/// Provides a concise, one-line method for setting `border-radius` on both the
+/// top-right and bottom-right of a box.
 ///
 /// @argument {number (with unit)} $radii
 ///
@@ -31,7 +31,7 @@
 ///     @include border-right-radius(3px);
 ///   }
 ///
-/// @example css
+///   // CSS Output
 ///   .element {
 ///     border-bottom-right-radius: 3px;
 ///     border-top-right-radius: 3px;
@@ -42,8 +42,8 @@
   border-top-right-radius: $radii;
 }
 
-/// Provides a shorthand syntax to add `border-radius` to both the bottom-left
-/// and bottom-right of an element.
+/// Provides a concise, one-line method for setting `border-radius` on both the
+/// bottom-left and bottom-right of a box.
 ///
 /// @argument {number (with unit)} $radii
 ///
@@ -52,7 +52,7 @@
 ///     @include border-bottom-radius(2px);
 ///   }
 ///
-/// @example css
+///   // CSS Output
 ///   .element {
 ///     border-bottom-left-radius: 2px;
 ///     border-bottom-right-radius: 2px;
@@ -63,8 +63,8 @@
   border-bottom-right-radius: $radii;
 }
 
-/// Provides a shorthand syntax to add `border-radius` to both the top-left
-/// and bottom-left of an element.
+/// Provides a concise, one-line method for setting `border-radius` on both the
+/// top-left and bottom-left of a box.
 ///
 /// @argument {number (with unit)} $radii
 ///
@@ -73,7 +73,7 @@
 ///     @include border-left-radius(1px);
 ///   }
 ///
-/// @example css
+///   // CSS Output
 ///   .element {
 ///     border-bottom-left-radius: 1px;
 ///     border-top-left-radius: 1px;

data/core/bourbon/library/_border-style.scss

@@ -1,17 +1,18 @@
 @charset "UTF-8";
 
-/// Provides a quick method for targeting `border-style` on specific sides of a
-/// box. Use a `null` value to “skip” a side.
+/// 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.
 ///
-/// @argument {arglist} $values
-///   List of border styles, defined as CSS shorthand.
+/// @argument {list} $values
+///   List of border styles; accepts CSS shorthand.
 ///
 /// @example scss
 ///   .element {
 ///     @include border-style(dashed null solid);
 ///   }
 ///
-/// @example css
+///   // CSS Output
 ///   .element {
 ///     border-bottom-style: solid;
 ///     border-top-style: dashed;
@@ -19,6 +20,6 @@
 ///
 /// @require {mixin} _directional-property
 
-@mixin border-style($values...) {
-  @include _directional-property(border, style, $values...);
+@mixin border-style($values) {
+  @include _directional-property(border, style, $values);
 }

data/core/bourbon/library/_border-width.scss

@@ -1,17 +1,18 @@
 @charset "UTF-8";
 
-/// Provides a quick method for targeting `border-width` on specific sides of a
-/// box. Use a `null` value to “skip” a side.
+/// 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.
 ///
-/// @argument {arglist} $values
-///   List of border widths, defined as CSS shorthand.
+/// @argument {list} $values
+///   List of border widths; accepts CSS shorthand.
 ///
 /// @example scss
 ///   .element {
 ///     @include border-width(1em null 20px);
 ///   }
 ///
-/// @example css
+///   // CSS Output
 ///   .element {
 ///     border-bottom-width: 20px;
 ///     border-top-width: 1em;
@@ -19,6 +20,6 @@
 ///
 /// @require {mixin} _directional-property
 
-@mixin border-width($values...) {
-  @include _directional-property(border, width, $values...);
+@mixin border-width($values) {
+  @include _directional-property(border, width, $values);
 }

data/core/bourbon/library/_buttons.scss

@@ -16,7 +16,7 @@
 ///     background-color: #f00;
 ///   }
 ///
-/// @example css
+///   // CSS Output
 ///   button,
 ///   [type='button'],
 ///   [type='reset'],
@@ -35,7 +35,7 @@ $all-buttons: _assign-inputs($_buttons-list);
 ///     background-color: #00f;
 ///   }
 ///
-/// @example css
+///   // CSS Output
 ///   button:active,
 ///   [type='button']:active,
 ///   [type='reset']:active,
@@ -54,7 +54,7 @@ $all-buttons-active: _assign-inputs($_buttons-list, active);
 ///     background-color: #0f0;
 ///   }
 ///
-/// @example css
+///   // CSS Output
 ///   button:focus,
 ///   [type='button']:focus,
 ///   [type='reset']:focus,
@@ -73,7 +73,7 @@ $all-buttons-focus: _assign-inputs($_buttons-list, focus);
 ///     background-color: #0f0;
 ///   }
 ///
-/// @example css
+///   // CSS Output
 ///   button:hover,
 ///   [type='button']:hover,
 ///   [type='reset']:hover,

data/core/bourbon/library/_clearfix.scss

@@ -2,14 +2,14 @@
 
 /// Provides an easy way to include a clearfix for containing floats.
 ///
-/// @link http://goo.gl/yP5hiZ
+/// @link https://goo.gl/yP5hiZ
 ///
 /// @example scss
 ///   .element {
 ///     @include clearfix;
 ///   }
 ///
-/// @example css
+///   // CSS Output
 ///   .element::after {
 ///     clear: both;
 ///     content: "";

data/core/bourbon/library/_contrast-switch.scss

@@ -1,41 +1,59 @@
 @charset "UTF-8";
 
-/// Switches between two colors based on the lightness of a another color. Great
-/// for building button styles.
+/// 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.
+///
+///   [ternary operator]: https://goo.gl/ccfLqi
+///   [WCAG 2.0 specification]: https://goo.gl/zhQuYA
 ///
 /// @argument {color} $base-color
 ///   The color to evaluate lightness against.
 ///
 /// @argument {color} $dark-color [#000]
-///   The color to be output when `$base-color` is light.
+///   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.
 ///
 /// @argument {color} $light-color [#fff]
-///   The color to be output when `$base-color` is dark.
+///   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.
 ///
 /// @return {color}
 ///
 /// @example scss
-///   .first-element {
+///   .element {
 ///     color: contrast-switch(#bae6e6);
 ///   }
 ///
-///   .second-element {
+///   // CSS Output
+///   .element {
+///     color: #000;
+///   }
+///
+/// @example scss
+///   .element {
 ///     $button-color: #2d72d9;
 ///     background-color: $button-color;
 ///     color: contrast-switch($button-color, #222, #eee);
 ///   }
 ///
-/// @example css
-///   .first-element {
-///     color: #000;
-///   }
-///
-///   .second-element {
+///   // CSS Output
+///   .element {
 ///     background-color: #2d72d9;
 ///     color: #eee;
 ///   }
 ///
-/// @require {function} _is-light
+/// @require {function} _retrieve-bourbon-setting
+///
+/// @require {function} _is-color
+///
+/// @require {function} _contrast-ratio
 ///
 /// @since 5.0.0
 
@@ -55,6 +73,10 @@
     @error "`#{$light-color}` is not a valid color for the `$light-color` " +
            "argument in the `contrast-switch` function.";
   } @else {
-    @return if(_is-light($base-color), $dark-color, $light-color);
+    $-contrast-to-dark: _contrast-ratio($base-color, $dark-color);
+    $-contrast-to-light: _contrast-ratio($base-color, $light-color);
+    $-prefer-dark: $-contrast-to-dark >= $-contrast-to-light;
+
+    @return if($-prefer-dark, $dark-color, $light-color);
   }
 }

data/core/bourbon/library/_ellipsis.scss

@@ -13,7 +13,7 @@
 ///     @include ellipsis;
 ///   }
 ///
-/// @example css
+///   // CSS Output
 ///   .element {
 ///     display: inline-block;
 ///     max-width: 100%;

data/core/bourbon/library/_font-face.scss

@@ -11,11 +11,12 @@
 ///
 /// @argument {string} $asset-pipeline [false]
 ///   Set to `true` if you’re using the Rails Asset Pipeline (place the fonts
-///   in `app/assets/fonts/`).
+///   in `app/assets/fonts/`). Can also be set globally using the
+///   `rails-asset-pipeline` key in the Bourbon settings.
 ///
 /// @argument {string | list} $file-formats [("ttf", "woff2", "woff")]
-///   Pass a list of file formats to support,
-///   for example ("eot", "ttf", "svg", "woff2", "woff").
+///   List of the font file formats to include. Can also be set globally using
+///   the `global-font-file-formats` key in the Bourbon settings.
 ///
 /// @content
 ///   Any additional CSS properties that are included in the `@include`
@@ -32,7 +33,7 @@
 ///     font-weight: 400;
 ///   }
 ///
-/// @example css
+///   // CSS Output
 ///   @font-face {
 ///     font-family: "source-sans-pro";
 ///     src: url("fonts/source-sans-pro-regular.woff2") format("woff2"),

data/core/bourbon/library/_font-stacks.scss

@@ -1,10 +1,20 @@
 @charset "UTF-8";
 
-////
+/// A variable that outputs a Helvetica font stack.
+///
+/// @link https://goo.gl/uSJvZe
+///
 /// @type list
 ///
-/// @link goo.gl/Cxb26i
-////
+/// @example scss
+///   .element {
+///     font-family: $font-stack-helvetica;
+///   }
+///
+///   // CSS Output
+///   .element {
+///     font-family: "Helvetica Neue", "Helvetica", "Arial", sans-serif;
+///   }
 
 $font-stack-helvetica: (
   "Helvetica Neue",
@@ -13,6 +23,22 @@ $font-stack-helvetica: (
   sans-serif,
 );
 
+/// A variable that outputs a Lucida Grande font stack.
+///
+/// @link https://goo.gl/R5UyYE
+///
+/// @type list
+///
+/// @example scss
+///   .element {
+///     font-family: $font-stack-lucida-grande;
+///   }
+///
+///   // CSS Output
+///   .element {
+///     font-family: "Lucida Grande", "Lucida Sans Unicode", "Geneva", "Verdana", sans-serif;
+///   }
+
 $font-stack-lucida-grande: (
   "Lucida Grande",
   "Lucida Sans Unicode",
@@ -21,26 +47,82 @@ $font-stack-lucida-grande: (
   sans-serif,
 );
 
+/// A variable that outputs a Verdana font stack.
+///
+/// @link https://goo.gl/yGXWSS
+///
+/// @type list
+///
+/// @example scss
+///   .element {
+///     font-family: $font-stack-verdana;
+///   }
+///
+///   // CSS Output
+///   .element {
+///     font-family: "Verdana", "Geneva", sans-serif;
+///   }
+
 $font-stack-verdana: (
   "Verdana",
   "Geneva",
   sans-serif,
 );
 
+/// A variable that outputs a system font stack.
+///
+/// @link https://goo.gl/LHRZIf
+///
+/// @type list
+///
+/// @example scss
+///   .element {
+///     font-family: $font-stack-system;
+///   }
+///
+///   // CSS Output
+///   .element {
+///     font-family: -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-system: (
   -apple-system,
   BlinkMacSystemFont,
+  "Avenir Next",
+  "Avenir",
   "Segoe UI",
+  "Lucida Grande",
+  "Helvetica Neue",
+  "Helvetica",
+  "Fira Sans",
   "Roboto",
+  "Noto",
+  "Droid Sans",
+  "Cantarell",
   "Oxygen",
   "Ubuntu",
-  "Cantarell",
-  "Fira Sans",
-  "Droid Sans",
-  "Helvetica Neue",
+  "Franklin Gothic Medium",
+  "Century Gothic",
+  "Liberation Sans",
   sans-serif,
 );
 
+/// A variable that outputs a Garamond font stack.
+///
+/// @link https://goo.gl/QQFEkV
+///
+/// @type list
+///
+/// @example scss
+///   .element {
+///     font-family: $font-stack-garamond;
+///   }
+///
+///   // CSS Output
+///   .element {
+///     font-family: "Garamond", "Baskerville", "Baskerville Old Face", "Hoefler Text", "Times New Roman", serif;
+///   }
+
 $font-stack-garamond: (
   "Garamond",
   "Baskerville",
@@ -50,6 +132,22 @@ $font-stack-garamond: (
   serif,
 );
 
+/// A variable that outputs a Georgia font stack.
+///
+/// @link https://goo.gl/wtzVPy
+///
+/// @type list
+///
+/// @example scss
+///   .element {
+///     font-family: $font-stack-georgia;
+///   }
+///
+///   // CSS Output
+///   .element {
+///     font-family: "Georgia", "Times", "Times New Roman", serif;
+///   }
+
 $font-stack-georgia: (
   "Georgia",
   "Times",
@@ -57,6 +155,22 @@ $font-stack-georgia: (
   serif,
 );
 
+/// A variable that outputs a Hoefler Text font stack.
+///
+/// @link https://goo.gl/n7U7zx
+///
+/// @type list
+///
+/// @example scss
+///   .element {
+///     font-family: $font-stack-hoefler-text;
+///   }
+///
+///   // CSS Output
+///   .element {
+///     font-family: "Hoefler Text", "Baskerville Old Face", "Garamond", "Times New Roman", serif;
+///   }
+
 $font-stack-hoefler-text: (
   "Hoefler Text",
   "Baskerville Old Face",
@@ -65,12 +179,44 @@ $font-stack-hoefler-text: (
   serif,
 );
 
+/// A variable that outputs a Consolas font stack.
+///
+/// @link https://goo.gl/iKrtqv
+///
+/// @type list
+///
+/// @example scss
+///   .element {
+///     font-family: $font-stack-consolas;
+///   }
+///
+///   // CSS Output
+///   .element {
+///     font-family: "Consolas", "monaco", monospace;
+///   }
+
 $font-stack-consolas: (
   "Consolas",
   "monaco",
   monospace,
 );
 
+/// A variable that outputs a Courier New font stack.
+///
+/// @link https://goo.gl/bHfWMP
+///
+/// @type list
+///
+/// @example scss
+///   .element {
+///     font-family: $font-stack-courier-new;
+///   }
+///
+///   // CSS Output
+///   .element {
+///     font-family: "Courier New", "Courier", "Lucida Sans Typewriter", "Lucida Typewriter", monospace;
+///   }
+
 $font-stack-courier-new: (
   "Courier New",
   "Courier",
@@ -79,8 +225,24 @@ $font-stack-courier-new: (
   monospace,
 );
 
+/// A variable that outputs a Monaco font stack.
+///
+/// @link https://goo.gl/9PgKDO
+///
+/// @type list
+///
+/// @example scss
+///   .element {
+///     font-family: $font-stack-monaco;
+///   }
+///
+///   // CSS Output
+///   .element {
+///     font-family: "Monaco", "Consolas", "Lucida Console", monospace;
+///   }
+
 $font-stack-monaco: (
-  "monaco",
+  "Monaco",
   "Consolas",
   "Lucida Console",
   monospace,