zen-grids 1.2 → 1.3

data/README.txt

@@ -7,6 +7,8 @@ designs. With an easy-to-use Sass mixin set, the Zen Grids system can be applied
 to an infinite number of layouts, including responsive, adaptive, fluid and
 fixed-width layouts.
 
+More information can be found at http://zengrids.com
+
 
 USAGE
 -----

data/stylesheets/zen/_background-grid.scss

@@ -1,3 +1,8 @@
+//
+// THIS MIXIN IS DEPRECATED. It has been completely re-written (and renamed)
+// in Zen Grids 2.0.
+//
+
 @import "zen/grids";
 
 // Specify the column background color.
@@ -19,6 +24,8 @@ $bg-grid-color: #ffdede !default;
   $flow-direction: $zen-float-direction
 ) {
 
+  @warn "The -experimental-bg-grid() mixin has been DEPRECATED and will be removed in Zen Grids 2.0.";
+
   // Internal variables.
   $dir: $flow-direction;
   @if $zen-reverse-all-floats {

data/stylesheets/zen/_grids.scss

@@ -3,47 +3,41 @@
 //
 
 
-// Specify the number of columns in the grid.
-$zen-column-count: 1 !default;
+// Specify the number of columns in the grid. @see http://zengrids.com/help/#zen-column-count
+$zen-column-count                 : 1           !default;
 
-// Specify the width of the gutters; half of the gutter will be placed on each
-// side of a grid column.
-$zen-gutter-width: 20px !default;
+// Specify the width of the gutters (as padding). @see http://zengrids.com/help/#zen-gutter-width
+$zen-gutter-width                 : 20px        !default;
 
-// You can generate more efficient CSS if you manually apply the
-// zen-grid-item-base mixin to all grid items from within a single ruleset.
-$zen-auto-include-item-base: true !default;
-$zen-auto-include-flow-item-base: true !default;
+// @see http://zengrids.com/help/#zen-auto-include-item-base
+$zen-auto-include-item-base       : true        !default;
+$zen-auto-include-flow-item-base  : true        !default;
 
-// Specify the width of the entire grid. Defaults to 100% for a fluid responsive
-// design, but you can change this to a pixel value if you need a fixed grid.
-$zen-grid-width: 100% !default;
+// Specify the width of the entire grid. @see http://zengrids.com/help/#zen-grid-width
+$zen-grid-width                   : 100%        !default;
 
-// The box-sizing polyfill for IE6/7 requires an absolute path to the
-// boxsizing.htc file. See https://github.com/Schepp/box-sizing-polyfill
-$box-sizing-polyfill-path: "" !default;
+// The box-sizing polyfill for IE6/7 requires an absolute path. @see http://zengrids.com/help/#box-sizing-polyfill-path
+$box-sizing-polyfill-path         : ""          !default;
 
-// Specify the CSS3 box-sizing method. The default, "border-box", is compatible
-// with all modern browsers, including IE 8 and later. Use "content-box" for
-// wider compatibility (Note: you'll also need to set $legacy-support-for-ie7
-// and $legacy-support-for-ie6 to true.)
-$zen-box-sizing: border-box !default;
+// Specify the CSS3 box-sizing method. @see http://zengrids.com/help/#zen-box-sizing
+$zen-box-sizing                   : border-box  !default;
 
-// Turn off IE6/7 support since we're defaulting to box-sizing: border-box.
-$legacy-support-for-ie7: false !default;
-$legacy-support-for-ie6: false !default;
+// @see http://zengrids.com/help/#legacy-support-for-ie7
+$legacy-support-for-ie7           : false       !default;
+$legacy-support-for-ie6           : false       !default;
 
-// Specify the default floating direction for zen's mixins.
-$zen-float-direction: left !default;
+// Specify the default floating direction for zen's mixins. @see http://zengrids.com/help/#zen-float-direction
+$zen-float-direction              : left        !default;
 
-// This is a helper variable for RTL layouts.
-$zen-reverse-all-floats: false !default;
+// Reverse the floating direction in all zen's mixins. @see http://zengrids.com/help/#zen-reverse-all-floats
+$zen-reverse-all-floats           : false       !default;
 
 
 //
 // Apply this to the grid container element.
+// @see http://zengrids.com/help/#zen-grid-container
 //
-@mixin zen-grid-container () {
+@mixin zen-grid-container {
   @if ($legacy-support-for-ie6 or $legacy-support-for-ie7) {
     *position: relative; // @TODO: This is a pre-IE8 line of code; don't remember why its needed.
   }
@@ -63,9 +57,9 @@ $zen-reverse-all-floats: false !default;
 
 //
 // Apply this to any grid item that is also a grid container element for a
-// nested grid. It must be applied after the zen-grid-item() mixin.
+// nested grid. @see http://zengrids.com/help/#zen-nested-container
 //
-@mixin zen-nested-container () {
+@mixin zen-nested-container {
   padding: {
     left: 0;
     right: 0;
@@ -73,28 +67,26 @@ $zen-reverse-all-floats: false !default;
 }
 
 //
-// Apply this to each grid item. Set the $column-span to the number of columns
-// that the grid item spans. And set the $column-position to the column number
-// the grid item starts on.
+// Apply this to each grid item. @see http://zengrids.com/help/#zen-grid-item
 //
-// For grid items that are floated right, the $column-position is counted
-// from the right instead of from the left.
-//
-@mixin zen-grid-item (
+@mixin zen-grid-item(
   $column-span,
   $column-position,
-  $float-direction: $zen-float-direction,
-  $column-count: $zen-column-count,
-  $gutter-width: $zen-gutter-width,
-  $grid-width: $zen-grid-width,
-  $box-sizing: $zen-box-sizing,
-  $reverse-all-floats: $zen-reverse-all-floats,
-  $auto-include-item-base: $zen-auto-include-item-base
+  $float-direction          : $zen-float-direction,
+  $column-count             : $zen-column-count,
+  $gutter-width             : $zen-gutter-width,
+  $grid-width               : $zen-grid-width,
+  $box-sizing               : $zen-box-sizing,
+  $reverse-all-floats       : $zen-reverse-all-floats,
+  $auto-include-item-base   : $zen-auto-include-item-base
 ) {
 
   // Calculate the unit width.
   $unit-width: zen-unit-width($column-count, $grid-width);
 
+  // Calculate the item's width.
+  $width: zen-grid-item-width($column-span, $column-count, $gutter-width, $grid-width, $box-sizing);
+
   // Determine the float direction and its reverse.
   $dir: $float-direction;
   @if $reverse-all-floats {
@@ -103,15 +95,6 @@ $zen-reverse-all-floats: false !default;
   $rev: zen-direction-flip($dir);
 
   float: $dir;
-  $width: $column-span * $unit-width;
-  @if $box-sizing == content-box {
-    @if not comparable($width, $gutter-width) {
-      $units-gutter: unit($gutter-width);
-      $units-grid: unit($grid-width);
-      @warn "The layout cannot be calculated correctly; when using box-sizing: content-box, the units of the gutter (#{$units-gutter} did not match the units of the grid width (#{$units-grid}).";
-    }
-    $width: $width - $gutter-width;
-  }
   width: $width;
   margin: {
     #{$dir}: ($column-position - 1) * $unit-width;
@@ -126,22 +109,13 @@ $zen-reverse-all-floats: false !default;
 
 //
 // Applies a standard set of properites to all grid items in the layout.
+// @see http://zengrids.com/help/#zen-grid-item-base
 //
-// See the note about the $zen-auto-include-item-base and
-// $zen-auto-include-flow-item-base variables for when to use this mixin.
-//
-// The mixin has the following optional parameters, but its better to use the
-// $zen-gutter-width and $zen-box-sizing variables instead:
-// - $gutter-width: Half of this value is applied as padding to the left and
-//   right sides of the item.
-// - $box-sizing: The type of CSS3 box model each box should use. Can be set to
-//   content-box or border-box. Defaults to content-box, but border-box is way
-//   cooler. IE 6 and 7 don't support border-box.
-@mixin zen-grid-item-base (
-  $gutter-width: $zen-gutter-width,
-  $box-sizing: $zen-box-sizing,
-  $flow-direction: $zen-float-direction,
-  $reverse-all-flows: $zen-reverse-all-floats
+@mixin zen-grid-item-base(
+  $gutter-width       : $zen-gutter-width,
+  $box-sizing         : $zen-box-sizing,
+  $flow-direction     : $zen-float-direction,
+  $reverse-all-flows  : $zen-reverse-all-floats
 ) {
 
   $dir: $flow-direction;
@@ -160,9 +134,12 @@ $zen-reverse-all-floats: false !default;
     -ms-box-sizing: border-box;
     box-sizing: border-box;
   }
-  // Prevent borders since they'll break the layout with content-box.
+  // Prevent left/right borders since they'll break the layout with content-box.
   @if $box-sizing == content-box {
-    border: 0 !important;
+    border: {
+      left: 0 !important;
+      right: 0 !important;
+    }
   }
   // Prevent overflowing content from being hidden beneath other grid items.
   word-wrap: break-word; // A very nice CSS3 property.
@@ -185,11 +162,12 @@ $zen-reverse-all-floats: false !default;
 }
 
 //
-// Apply this to content boxes that need to be cleared below other content boxes.
+// Apply this to grid items that need to be cleared below other grid items.
+// @see http://zengrids.com/help/#zen-clear
 //
-@mixin zen-clear (
-  $float-direction: $zen-float-direction,
-  $reverse-all-floats: $zen-reverse-all-floats
+@mixin zen-clear(
+  $float-direction      : $zen-float-direction,
+  $reverse-all-floats   : $zen-reverse-all-floats
 ) {
   // Determine the float direction.
   $dir: $float-direction;
@@ -201,10 +179,11 @@ $zen-reverse-all-floats: false !default;
 
 //
 // Apply this to flow items that need to be floated.
+// @see http://zengrids.com/help/#zen-float
 //
-@mixin zen-float (
-  $float-direction: $zen-float-direction,
-  $reverse-all-floats: $zen-reverse-all-floats
+@mixin zen-float(
+  $float-direction      : $zen-float-direction,
+  $reverse-all-floats   : $zen-reverse-all-floats
 ) {
   // Determine the float direction.
   $dir: $float-direction;
@@ -216,40 +195,26 @@ $zen-reverse-all-floats: false !default;
 
 //
 // Apply this to an HTML item that is in the normal flow of a document to help
-// align it to the grid. Set the $column-span to the number of columns that the
-// HTML element should span. For responsive layouts with a percentage-based grid
-// width, set the $parent-column-count to the number of columns that the parent
-// element spans; fixed-unit layouts using px, em, etc. do not need to specify
-// this.
+// align it to the grid. @see http://zengrids.com/help/#zen-float
 //
-// Unlike the zen-grid-item() mixin, this mixin does not float the HTML item; it
-// also does not have a half-gutter on each side. By default, it has no gutter
-// in the "alpha position" (the left side) and a full gutter in the "omega
-// position" (the right side.) You can turn on or off the alpha and omega
-// gutters by setting the $alpha-gutter and $omega-gutter parameters to true or
-// false.
-//
-// Note: when the $flow-direction is set to right (for RTL languages), the alpha
-// position is on the right and the omega position is on the left.
-//
-@mixin zen-grid-flow-item (
+@mixin zen-grid-flow-item(
   $column-span,
-  $parent-column-count: false,
-  $alpha-gutter: false,
-  $omega-gutter: true,
-  $flow-direction: $zen-float-direction,
-  $column-count: $zen-column-count,
-  $gutter-width: $zen-gutter-width,
-  $grid-width: $zen-grid-width,
-  $box-sizing: $zen-box-sizing,
-  $reverse-all-flows: $zen-reverse-all-floats,
-  $auto-include-flow-item-base: $zen-auto-include-flow-item-base
+  $parent-column-count          : false,
+  $alpha-gutter                 : false,
+  $omega-gutter                 : true,
+  $flow-direction               : $zen-float-direction,
+  $column-count                 : $zen-column-count,
+  $gutter-width                 : $zen-gutter-width,
+  $grid-width                   : $zen-grid-width,
+  $box-sizing                   : $zen-box-sizing,
+  $reverse-all-flows            : $zen-reverse-all-floats,
+  $auto-include-flow-item-base  : $zen-auto-include-flow-item-base
 ) {
 
   $columns: $column-count;
   @if unit($grid-width) == "%" {
     @if $parent-column-count == false {
-      @warn "For responsive layouts with a percentage-based grid width, you must set the $column-count to the number of columns that the parent element spans.";
+      @warn "For responsive layouts with a percentage-based grid width, you must set the $parent-column-count to the number of columns that the parent element spans.";
     }
     @else {
       $columns: $parent-column-count;
@@ -262,35 +227,64 @@ $zen-reverse-all-floats: false !default;
   }
   $rev: zen-direction-flip($dir);
 
-  // Calculate the item's width.
-  $width: zen-grid-item-width($column-span, $columns, $grid-width);
-  @if $box-sizing == content-box {
-    @if not comparable($width, $gutter-width) {
-      $units-gutter: unit($gutter-width);
-      $units-grid: unit($grid-width);
-      @warn "The layout cannot be calculated correctly; when using box-sizing: content-box, the units of the gutter (#{$units-gutter} did not match the units of the grid width (#{$units-grid}).";
-    }
-    $width: $width - $gutter-width;
-  }
-  width: $width;
-
   // Auto-apply the unit base mixin.
   @if $auto-include-flow-item-base {
     @include zen-grid-item-base($gutter-width, $box-sizing);
   }
 
-  // Ensure the HTML item either has a full gutter or no gutter on each side.
-  padding-#{$dir}: 0;
-  @if $alpha-gutter {
-    margin-#{$dir}: $gutter-width;
-  }
-  $offset: ($columns - $column-span) * $gutter-width / $columns;
-  padding-#{$rev}: $offset;
-  @if $omega-gutter {
-    margin-#{$rev}: $gutter-width - $offset;
+  // Calculate the item's width.
+  $width: zen-grid-item-width($column-span, $columns, $gutter-width, $grid-width, $box-sizing);
+
+  @if unit($grid-width) == "%" {
+    // Our percentage $width is off if the parent has $gutter-width padding.
+    // Calculate an adjusted gutter to fix the width.
+    $adjusted-gutter: ($columns - $column-span) * $gutter-width / $columns;
+
+    width: $width;
+
+    // Ensure the HTML item either has a full gutter or no gutter on each side.
+    padding-#{$dir}: 0;
+    @if $alpha-gutter {
+      margin-#{$dir}: $gutter-width;
+    }
+    padding-#{$rev}: $adjusted-gutter;
+    @if $omega-gutter {
+      margin-#{$rev}: $gutter-width - $adjusted-gutter;
+    }
+    @else {
+      margin-#{$rev}: -($adjusted-gutter);
+    }
   }
   @else {
-    margin-#{$rev}: -($offset);
+    @if $alpha-gutter and $omega-gutter {
+      width: $width;
+      @if $gutter-width != 0 {
+        margin: {
+          #{$dir}: zen-half-gutter($gutter-width, left, $dir);
+          #{$rev}: zen-half-gutter($gutter-width, right, $dir);
+        }
+      }
+    }
+    @else if not $alpha-gutter and not $omega-gutter {
+      width: if($box-sizing == border-box, ($width - $gutter-width), $width);
+      @if $gutter-width != 0 {
+        padding: {
+          left: 0;
+          right: 0;
+        }
+      }
+    }
+    @else {
+      width: $width;
+      @if $omega-gutter {
+        padding-#{$dir}: 0;
+        padding-#{$rev}: $gutter-width;
+      }
+      @else {
+        padding-#{$dir}: $gutter-width;
+        padding-#{$rev}: 0;
+      }
+    }
   }
 }
 
@@ -299,11 +293,11 @@ $zen-reverse-all-floats: false !default;
 // Helper functions for the Zen mixins.
 //
 
-// Returns a half gutter width.
+// Returns a half gutter width. @see http://zengrids.com/help/#zen-half-gutter
 @function zen-half-gutter(
-  $gutter-width: $zen-gutter-width,
-  $gutter-side: $zen-float-direction,
-  $flow-direction: $zen-float-direction
+  $gutter-width     : $zen-gutter-width,
+  $gutter-side      : $zen-float-direction,
+  $flow-direction   : $zen-float-direction
 ) {
   $half-gutter: $gutter-width / 2;
   // Special handling in case gutter has an odd number of pixels.
@@ -318,10 +312,10 @@ $zen-reverse-all-floats: false !default;
   @return $half-gutter;
 }
 
-// Calculates the unit width of a column.
-@function zen-unit-width (
-  $column-count: $zen-column-count,
-  $grid-width: $zen-grid-width
+// Calculates the unit width of a column. @see http://zengrids.com/help/#zen-unit-width
+@function zen-unit-width(
+  $column-count   : $zen-column-count,
+  $grid-width     : $zen-grid-width
 ) {
   $unit-width: $grid-width / $column-count;
   @if unit($unit-width) == "px" and floor($unit-width) != ceil($unit-width) {
@@ -331,16 +325,31 @@ $zen-reverse-all-floats: false !default;
 }
 
 // Calculates the width of a grid item that spans the specified number of columns.
-@function zen-grid-item-width (
+// @see http://zengrids.com/help/#zen-grid-item-width
+@function zen-grid-item-width(
   $column-span,
-  $column-count: $zen-column-count,
-  $grid-width: $zen-grid-width
+  $column-count   : $zen-column-count,
+  $gutter-width   : $zen-gutter-width,
+  $grid-width     : $zen-grid-width,
+  $box-sizing     : $zen-box-sizing
 ) {
-  @return $column-span * zen-unit-width($column-count, $grid-width);
+  $width: $column-span * zen-unit-width($column-count, $grid-width);
+  @if $box-sizing == content-box {
+    @if not comparable($width, $gutter-width) {
+      $units-gutter: unit($gutter-width);
+      $units-grid: unit($grid-width);
+      @warn "The layout cannot be calculated correctly; when using box-sizing: content-box, the units of the gutter (#{$units-gutter} did not match the units of the grid width (#{$units-grid}).";
+    }
+    $width: $width - $gutter-width;
+  }
+  @return $width;
 }
 
 // Returns the opposite direction, given "left" or "right".
-@function zen-direction-flip($dir) {
+// @see http://zengrids.com/help/#zen-direction-flip
+@function zen-direction-flip(
+  $dir
+) {
   @if $dir == left {
     @return right;
   }

data/templates/project/_init.scss

@@ -0,0 +1,20 @@
+//
+// @file
+// This file sets up all our variables and load all the modules we need for all
+// generated CSS in this project. To use it, simply: @import "init";
+//
+
+// Legacy browser variables for Compass.
+$legacy-support-for-ie6     : false;
+$legacy-support-for-ie7     : false;
+
+// Set up Zen Grids.
+$zen-column-count           : 1;
+$zen-gutter-width           : 20px;
+$zen-auto-include-item-base : false;
+
+//
+// Import our modules.
+//
+@import "zen";
+@import "visually-hidden";