underoos 1.0.0 → 1.1.0

data/app/assets/stylesheets/mixins/_coloring.sass

@@ -1,5 +1,14 @@
 
-// Fills a background color and darkens the border based off a percentage
+//~
+// Colorizing mixins to extend the native Sass functions.
+//
+// Mixin                       | Params                      | Usage
+// ----------------------------|-----------------------------|----------------------------------------------
+// `+background-darken-border` | `$color`, `$percentage:20%` | Fills a background color and darkens the border based off a percentage
+//
+// Notes:
+// - **Pro Tip!** Sass comes pre-baked with [killer native color methods](http://sass-lang.com/docs/yardoc/Sass/Script/Functions.html)
+
 @mixin background-darken-border($color, $percentage:20%)
   background-color: $color
   border: 1px solid darken($color, $percentage)

data/app/assets/stylesheets/mixins/_columns.sass

@@ -1,17 +1,30 @@
 
-// The base `column` settings, should be extended by all columns
+//~
+// Allows elements to take the shape of either a column or row within a grid environment.
+//
+// Mixin                | Usage
+// ---------------------|--------------------------------------------------------------------------------
+// `+base-column`       | The base `column` settings, should be extended by all columns
+// `+base-column-right` | An alternate base `column` which floats elements to the right
+// `+base-row`          | The base `row` settings, should be extended by all rows
+//
+// Notes:
+// - **Pro Tip!** There are helper classes for `.base-column`, `.base-row` and
+//   `.base-column-right` which can be used for extension with `@extend`
+//
+// Warnings:
+// - **Warning!** The column mixins all utilize `box-sizing: border-box` which is not supported in ie7
+
 @mixin base-column
   +box-sizing(border-box)
   display: block
   float: left
 
-// An alternate base `column` which floats elements to the right
 @mixin base-column-right
   +box-sizing(border-box)
   display: block
   float: right
 
-// The base `row` settings, should be extended by all rows
 @mixin base-row
   +box-sizing(border-box)
   +clearfixer

data/app/assets/stylesheets/mixins/_conversions.sass

@@ -1,25 +1,37 @@
 
-// Converts target `px` value to `em` in context constraints of the base font size
+//~
+// Functions for calculations and conversion between pixels, ems, rems and percentages.
+//
+// Function           | Params                                    | Usage
+// ------------------ | ----------------------------------------- | ----------------------------------------------
+// `to_em`            |  `$target_px`, `$context:$base_font_size` |  Converts target `px` value to `em` in context constraints of the base font size
+// `to_rem`           |  `$target_px`, `$context:$context_px`     |  Converts target `px` value to `rem` in context constraints of the user's base font size
+// `to_percent`       |  `$target_px`, `$context:$base_width`     |  Converts target `px` value to `percentage` in context constraints of the container's width
+// `vertical_pixel`   |  `$target_px`                             |  Returns the vertical rhythm in pixels calculated from the `$base_vertical` setting
+// `vertical_em`      |  `$target_px`                             |  Returns the vertical rhythm in em calculated from the `$base_vertical` setting
+// `vertical_percent` |  `$target_px`                             |  Returns the vertical rhythm in percent calculated from the `$base_vertical` setting
+//
+// Notes:
+// - **Important!** When calculating vertical rhythm, always pass in what the expected pixel value is for the element.
+//
+// Warnings:
+// - **Warning!** Define `$context_px`, `$base_font_size`, `$base_width` and `$base_vertical` prior to the functions being loaded.
+
 @function to_em($target_px, $context:$base_font_size)
   @return ($target_px / $context) * 1em
 
-// Converts target `px` value to `rem` in context constraints of the user's base font size
 @function to_rem($target_px, $context:$context_px)
   @return ($target_px / $context) * 1rem
 
-// Converts target `px` value to `percentage` in context constraints of the container's width
 @function to_percent($target_px, $context:$base_width)
   @return percentage($target_px / $context)
 
-// Returns the vertical rhythm in pixels calculated from the `$base_vertical` setting
 @function vertical_pixel($target_px)
   @return ($base_vertical / $target_px) * 1px
 
-// Returns the vertical rhythm in em calculated from the `$base_vertical` setting
 @function vertical_em($target_px)
   @return to_em(($base_vertical / $target_px), $base_font_size)
 
-// Returns the vertical rhythm in percent calculated from the `$base_vertical` setting
 @function vertical_percent($target_px)
   @return to_percent(($base_vertical / $target_px), $base_font_size)
 

data/app/assets/stylesheets/mixins/_font-size.sass

@@ -1,5 +1,20 @@
 
-// Use `rems` to insert a font size
+//~ Font size
+// Sets a `font-size` using `rems` with a pixel fallback.
+//
+// Arguments:
+// - `$target_px`              - The target font size in pixels
+// - `$context:$context_px`    - [_optional_] The context constraints of the
+//                               user's base font size
+//
+// Notes:
+// - **Heads Up!** Make sure not to include the `px` postfix when passing a size
+//
+// Examples:
+//    h1
+//      +font-size(48)
+//      color: blue
+
 @mixin font-size($target_px, $context:$context_px)
   font-size: $target_px * 1px
   font-size: to_rem($target_px, $context)

data/app/assets/stylesheets/mixins/_image-tools.sass

@@ -1,5 +1,16 @@
 
-// Image interpolation from http://stitchcss.com/
+//~ Image tools
+// Image interpolation settings based on [stich css](http://stitchcss.com/).
+//
+// Mixin                 | Usage
+// --------------------- | --------------------------------------------------------------------------------
+// `+sharpen-image`      |  Sharpen an image if it has become blurry due to upscaling or downscaling
+// `+high-quality-image` |  Improves rendering quality for images which may be upscaled or downscaled
+// `+low-quality-image`  |  Optimizes the rendering on images so they appear faster, but at a lower quality
+//
+// Warnings:
+// - **Warning!** These settings can have adverse effects in some browsers, test thoroughly.
+
 @mixin sharpen-image
   image-rendering: -moz-crisp-edges
   -ms-interpolation-mode: nearest-neighbor

data/app/assets/stylesheets/mixins/_inline-block.sass

@@ -0,0 +1,21 @@
+
+//~ Inline block
+// Mirrors the functionality found in [Compass](http://compass-style.org/reference/compass/css3/inline_block/)
+// and normalizes `inline-block` for [Bourbon](http://thoughtbot.com/bourbon/) by setting `vertical-align: middle`.
+//
+// The mixin also fixes support for ie7 if `$legacy-support-for-ie` is set to true.
+//
+// Examples:
+//    .breadcrumb > li
+//      +inline-block
+//      color: blue
+
+@mixin inline-block
+  display: inline-block
+  vertical-align: middle
+
+  @if $legacy-support-for-ie
+    zoom: 1
+    *display: inline
+    *vertical-align: auto
+

data/app/assets/stylesheets/mixins/_ir.sass

@@ -1,5 +1,18 @@
 
-// Image replacement
+//~ Image replacement
+// Hides text on an element when utilizing a `background-image` such as a logo or icon
+//
+// Notes:
+// - **Pro Tip!** There is a helper class for `.ir` which can be used for
+//   extension with `@extend`
+//
+// Examples:
+//    .footer .social-icon
+//      +ir
+//      background-image: $sprite-icons-img
+//      width: 24px
+//      height: 24px
+
 @mixin ir
   background-color: transparent
   border: 0

data/app/assets/stylesheets/mixins/_mixins.sass

@@ -1,5 +1,10 @@
 
+//~ # Mixins
+// Mixins automate common re-usable chunks of CSS, properties, selectors, and/or settings.
+
 // underoos mixins
+@import inline-block
+@import responsive
 @import arrows
 @import clearfixins
 @import coloring
@@ -11,4 +16,5 @@
 @import tab-focus
 @import timing-equations
 @import visibility
+@import sticky-footer
 

data/app/assets/stylesheets/mixins/_responsive.sass

@@ -0,0 +1,16 @@
+
+//~
+// Mixins for creating responsive behavior around structures and layouts.
+//
+// Mixin                 | Parameters    | Usage
+// --------------------- | ------------- | ---------------------
+// `+resize_containers`  | `$base_value` | Resize any containers based on the media query
+
+@mixin resize_containers($base_value)
+  .container
+    max-width: $base_value * 1px
+    &.fluid, &.fixed
+      max-width: none
+    &.fixed
+      width: $base_value * 1px
+

data/app/assets/stylesheets/mixins/_sticky-footer.sass

@@ -0,0 +1,52 @@
+
+//~ Sticky footer
+// Mixins for sticking and unsticking a footer to the bottom of a page.
+//
+// Mixin              | Parameters       | Usage
+// ------------------ | ---------------- | ---------------------
+// `+sticky_footer`   | `$footer-height` | Creates a sticky footer based off a fixed height on the footer element
+// `+unsticky_footer` | _none_           | Reverses the effect of the sticky_footer mixin, useful in media queries
+//
+// Requires the markup to contain a `.main`, `.content` and `.footer` elements.
+//
+// Examples:
+//    <body role="document">
+//      <section class="main">
+//        <section class="content">
+//          <section class="container" role="main">
+//          </section>
+//        </section>
+//      </section>
+//      <footer class="footer">
+//      </footer>
+//    </body>
+
+// Sticky Footer
+@mixin sticky_footer($footer-height)
+  html, body
+    height: 100%
+  .main
+    min-height: 100%
+    overflow-x: hidden
+    width: 100%
+  .content
+    padding-bottom: $footer-height
+  .footer
+    clear: both
+    position: relative
+    margin-top: $footer-height * -1
+    height: $footer-height
+    overflow: visible
+
+// Unstick the footer
+@mixin unsticky_footer()
+  html, body
+    height: auto
+  .main
+    min-height: none
+  .content
+    padding-bottom: 0
+  .footer
+    margin-top: 1em
+    height: auto
+

data/app/assets/stylesheets/mixins/_tab-focus.sass

@@ -1,5 +1,12 @@
 
-// Sets normal focus behavior
+//~ Tab focus
+// Resets the normal browser behavior for tab focusable content.
+//
+// Examples:
+//    input[type="radio"]:focus,
+//    input[type="checkbox"]:focus
+//      +tab-focus
+
 @mixin tab-focus
   outline: thin dotted
   outline: 5px auto -webkit-focus-ring-color

data/app/assets/stylesheets/mixins/_timing-equations.sass

@@ -1,5 +1,38 @@
 
-// CSS cubic-bezier timing functions courtesy of [jaukia](http://github.com/jaukia/easie)
+//~ Timing equations
+// Underoos comes packed with a number of cubic-bezier timing properties for
+// use with `transition-timing-function`. The timing functions are based on the
+// properties included with [Bourbon](http://thoughtbot.com/bourbon/).
+//
+// Property             | Example
+// -------------------- | -------------------------------------------------------
+// `default (linear)`   | <div class="sherpa-swatch"></div>
+// `$ease-in-quad`      | <div class="sherpa-swatch ease-in-quad"></div>
+// `$ease-in-cubic`     | <div class="sherpa-swatch ease-in-cubic"></div>
+// `$ease-in-quart`     | <div class="sherpa-swatch ease-in-quart"></div>
+// `$ease-in-quint`     | <div class="sherpa-swatch ease-in-quint"></div>
+// `$ease-in-sine`      | <div class="sherpa-swatch ease-in-sine"></div>
+// `$ease-in-expo`      | <div class="sherpa-swatch ease-in-expo"></div>
+// `$ease-in-circ`      | <div class="sherpa-swatch ease-in-circ"></div>
+// `$ease-in-back`      | <div class="sherpa-swatch ease-in-back"></div>
+// `$ease-out-quad`     | <div class="sherpa-swatch ease-out-quad"></div>
+// `$ease-out-cubic`    | <div class="sherpa-swatch ease-out-cubic"></div>
+// `$ease-out-quart`    | <div class="sherpa-swatch ease-out-quart"></div>
+// `$ease-out-quint`    | <div class="sherpa-swatch ease-out-quint"></div>
+// `$ease-out-sine`     | <div class="sherpa-swatch ease-out-sine"></div>
+// `$ease-out-expo`     | <div class="sherpa-swatch ease-out-expo"></div>
+// `$ease-out-circ`     | <div class="sherpa-swatch ease-out-circ"></div>
+// `$ease-out-back`     | <div class="sherpa-swatch ease-out-back"></div>
+// `$ease-in-out-quad`  | <div class="sherpa-swatch ease-in-out-quad"></div>
+// `$ease-in-out-cubic` | <div class="sherpa-swatch ease-in-out-cubic"></div>
+// `$ease-in-out-quart` | <div class="sherpa-swatch ease-in-out-quart"></div>
+// `$ease-in-out-quint` | <div class="sherpa-swatch ease-in-out-quint"></div>
+// `$ease-in-out-sine`  | <div class="sherpa-swatch ease-in-out-sine"></div>
+// `$ease-in-out-expo`  | <div class="sherpa-swatch ease-in-out-expo"></div>
+// `$ease-in-out-circ`  | <div class="sherpa-swatch ease-in-out-circ"></div>
+// `$ease-in-out-back`  | <div class="sherpa-swatch ease-in-out-back"></div>
+
+
 $ease-in-quad:      cubic-bezier(0.55, 0.085, 0.68, 0.53)
 $ease-in-cubic:     cubic-bezier(0.55, 0.055, 0.675, 0.19)
 $ease-in-quart:     cubic-bezier(0.895, 0.03, 0.685, 0.22)

data/app/assets/stylesheets/mixins/_visibility.sass

@@ -1,15 +1,29 @@
 
-// Totally hidden from screen readers and browsers
+//~
+// Controls various visibility settings applied to elements.
+//
+// Mixin            | Params  | Usage
+// ---------------- | ------- | ----------------------------------------------
+// `+hidden`        | _none_  | Totally hidden from screen readers and browsers
+// `+shown`         | _none_  | Reverse the effects of `hidden`
+// `+visuallyhidden`| _none_  | Only visually hidden, still available to screen readers
+// `+visuallyshown` | _none_  | Reverse the settings applied by `.visuallyhidden`
+// `+invisible`     | _none_  | Hide visually and from screenreaders, but maintain layout
+//
+// Notes:
+// - **Pro Tip!** All of these mixins are available as helper classes for use with `@extend`
+//
+// Warnings:
+// - **Warning!** When using `visuallyhidden` and `visuallyshown` with `box-shadow`, you'll need to add `clip:initial` to get the shadows to reappear
+
 @mixin hidden
   display: none !important
   visibility: hidden
 
-// Reverse the effects of hidden
 @mixin shown
   display: block
   visibility: visible
 
-// Only visually hidden, still available to screen readers
 @mixin visuallyhidden
   border: 0
   clip: rect(0 0 0 0)
@@ -28,16 +42,15 @@
     width: auto
     height: auto
 
-// Reverse the settings applied by `.visuallyhidden`
 @mixin visuallyshown
   clip: auto
+  clip: rect(auto auto auto auto)
   position: static
   overflow: visible
   margin: 0
   width: auto
   height: auto
 
-// Hide visually and from screenreaders, but maintain layout
 @mixin invisible
   visibility: hidden
 

data/app/assets/stylesheets/polyfills/_box-shadow.sass

@@ -1,4 +1,14 @@
 
+//~
+// Draws an outer or inset shadow around an element (supports up to 9 shadow parameters)
+//
+// Arguments:
+// - `$shadow-n` The normal or inset shadow properties to apply
+//
+// Examples:
+//    .element
+//      +box-shadow(inset 0 1px 1px rgba(0, 0, 0, 0.1), -1px -1px 5px 1px black)
+
 @mixin box-shadow($shadow-1:none, $shadow-2:false, $shadow-3:false, $shadow-4:false, $shadow-5:false, $shadow-6:false, $shadow-7:false, $shadow-8:false, $shadow-9:false)
   $full: combine($shadow-1, $shadow-2, $shadow-3, $shadow-4, $shadow-5, $shadow-6, $shadow-7, $shadow-8, $shadow-9)
   -webkit-box-shadow: $full

data/app/assets/stylesheets/polyfills/_box-sizing.sass

@@ -1,5 +1,14 @@
 
-// Box sizing content-box | border-box | inherit, matches compass and bourbon
+//~
+// Changes the box model used for calculating an elements width and height
+//
+// Arguments:
+// - `$type:border-box` Options: `content-box | border-box | inherit`
+//
+// Examples:
+//    .column
+//      +box-sizing(border-box)
+
 @mixin box-sizing ($type:border-box)
   $box: unquote($type)
   -webkit-box-sizing: $box

data/app/assets/stylesheets/polyfills/_functions.sass

@@ -1,5 +1,18 @@
 
-// A function used to combine and normalize multiple parameters for a polyfill (supports up to 9 values)
+//~ Combine
+// A function used by other polyfills to combine and normalize multiple parameters (supports up to 9 values)
+//
+// Arguments:
+// - `$value-1` The first property to combine
+// - `$value-2(-9)` Remaining properties to combine (defaults to `false`)
+// - `@return` The combined values for translation into the mixin
+//
+// Warnings:
+// - **Warning!** The combine function for mixin values only accepts 9 values, this is inline with the Bourbon library (Compass supports 10!)
+//
+// Examples:
+//    $full: combine($transition-1, $transition-2, $transition-3)
+
 @function combine($value-1, $value-2:false, $value-3:false, $value-4:false, $value-5:false, $value-6:false, $value-7:false, $value-8:false, $value-9:false)
   @if $value-2 == false and $value-3 == false and $value-4 == false and $value-5 == false and $value-6 == false and $value-7 == false and $value-8 == false and $value-9 == false
     @return $value-1

data/app/assets/stylesheets/polyfills/_opacity.sass

@@ -1,5 +1,14 @@
 
-// Opacity polyfill matches compass and bourbon
+//~
+// Provides cross browser opacity, values are between `0-1`.
+//
+// Arguments:
+// - `$alpha:1`
+//
+// Examples:
+//    .tooltip
+//      +opacity(0.5)
+
 @mixin opacity($alpha:1)
   filter: unquote("progid:DXImageTransform.Microsoft.Alpha(Opacity=#{round($alpha * 100)})")
   opacity: $alpha

data/app/assets/stylesheets/polyfills/_polyfills.sass

@@ -1,9 +1,16 @@
 
-// Import the polyfills for underoos if not using either Compass or Bourbon
+//~ # Polyfills
+// Most projects benefit greatly from using a library like [Compass](http://compass-style.org/)
+// or [Bourbon](http://thoughtbot.com/bourbon/). Underoos is not designed to
+// replace these libraries, but rather sit on top of them. There may be times
+// when using one of these libraries isn't an option, so Underoos provides a
+// few simple polyfill mixins in it's place.
+//
+// If a project uses Compass or Bourbon, make sure not to import these polyfills.
+
 @import functions
 @import box-shadow
 @import box-sizing
-@import inline-block
 @import opacity
 @import transition
 @import user-select