zen-grids 2.0.1 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f4c466e2e9bd85dbc464a608879a4254f6b526d8
-  data.tar.gz: f5fdd9ada83dba42d6be57505ae5cdefd51a029d
+  metadata.gz: d85c1798a0d60a010f9ce016b8f58c51e326cee0
+  data.tar.gz: 44595b1786ff0d5c91cfd5ce9af64bdd2357c423
 SHA512:
-  metadata.gz: 0b6e9b91a4b88d27bf80f3c36a974ee0eed373030bdcfdd72febe0075c0487425114b6ed0a33b43b74e3f5851130bff967ae98ea0a39bc5fa3b3c2f1df5d432b
-  data.tar.gz: b60ba0271d823683d2b763d0542ea935de01cd9c3759c52d7e63c3281ae14f9052a965bf6997d777b7a44b634ffd35fabe8b4396430ffab7be2c3dde95e44896
+  metadata.gz: f516ed94c05f6f7c93b4128829813f504bbba0e899badc6525e44c04a17188e1fc7127df22e02f3f062cf7436276cad9715c3ea3496e5c366b86a5a34e9d126f
+  data.tar.gz: 33eb2a00c39b5522f246d3d493468fd8198c4c33db9d86600a9cef08f750c8f7997a86c9daaf383b45089f01da6fe15d19503d9c874d2d462295a231d2f152c3

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zen-grids",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Zen Grids is an intuitive, flexible grid system to create responsive, adaptive, fluid and fixed-width layouts.",
   "homepage": "https://github.com/JohnAlbin/zen-grids",
   "bugs": {
@@ -22,8 +22,9 @@
   "main": "sass/_zen-grids.scss",
   "style": "sass/_zen-grids.scss",
   "eyeglass": {
-    "exports": "eyeglass-exports.js",
-    "needs": "^0.7.1"
+    "sassDir": "sass",
+    "exports": false,
+    "needs": "*"
   },
   "directories": {
     "lib": "sass",
@@ -35,13 +36,12 @@
   },
   "license": "GPL-2.0",
   "devDependencies": {
-    "chai": "^3.4.1",
-    "eslint": "^1.9.0",
-    "eyeglass": "^0.6.3",
-    "kss": "^2.1.0",
-    "mocha": "^2.3.4",
+    "chai": "^3.5.0",
+    "eslint": "^2.9.0",
+    "eyeglass": "^0.8.3",
+    "mocha": "^2.4.5",
     "node-sass-import-once": "^1.2.0",
-    "sassy-test": "^2.0.0",
+    "sassy-test": "^3.0.0",
     "support-for": "^1.0.0"
   }
 }

data/sass/homepage.md

@@ -0,0 +1,18 @@
+## Zen Grids 2.0
+
+### Reference documentation
+
+This documentation is for the new 2.0 version of Zen Grids. Pardon our dust while we get the _design_ up-to-date. Rest asured, the docs are up-to-date.
+
+For the previous Zen Grids 1.x documentation, see [v1.zengrids.com](http://v1.zengrids.com).
+
+### Modules
+
+Zen Grids 2.0 is divided into small modules that small and logical, making it easy to load and easier to understand.
+
+- [The “grids” module](section-grids.html) contains most of the configurable variables and mixins you’ll need to create a layout.
+- [The “flow” module](section-flow.html) helps align normal flow items within a grid.
+- [The “layout” module](section-layout.html) helps to create a set of grids for responsive designs.
+- [The “undo” module](section-undo.html) helps undo CSS applied in different media queries.
+- [The “helper functions” module](section-functions.html) contains functions you may need to create a layout.
+- [The “background” module](section-background.html) is used during development to help see the grid columns

data/sass/zen-grids/_background.scss

@@ -7,6 +7,8 @@
 // @import "zen-grids/background";
 // ```
 //
+// Weight: 20
+//
 // Style guide: background
 
 @import "./grids";
@@ -18,26 +20,38 @@
 //
 // Adds a background grid image to an element’s background.
 //
-// Common usage:
-// ```
-// @include zen-grid-background();
-// ```
-//
 // Since the mixins of Zen Grids use the `$column-position` for placement of grid items, the background grid image produced by this mixin numbers all of the columns. The `$grid-numbers` parameter specifies how to place the column numbers in the background grid image. By default, column numbers are displayed across the top of the background grid image and then displayed in reverse order along the bottom of the background grid image. `$grid-numbers` can be set to: `both` (the default), `top` (don’t display the bottom numbers), `bottom` (don’t display the top numbers), or `none` (don’t display any column numbers.)
 //
 // Note: when the `$direction` is set to `right` (for RTL languages), the column numbers are displayed right-to-left along the top and left-to-right along the bottom.
 //
 // The easiest way to align this background grid image to the actual grid is to apply this mixin to the same element that `zen-grid-container()` is applied to.
 //
-// $columns          - Defaults to `$zen-columns`
-// $gutters          - Defaults to `$zen-gutters`
-// $gutter-method    - Defaults to `$zen-gutter-method`
-// $grid-width       - Defaults to `$zen-grid-width`
-// $grid-color       - Defaults to `$zen-grid-color`
-// $grid-numbers     - Defaults to `$zen-grid-numbers`
-// $direction        - Defaults to `$zen-direction`
-// $switch-direction - Defaults to `$zen-switch-direction`
-// $rtl-selector     - Defaults to `$zen-rtl-selector`
+// ```
+// .layout-container {
+//   @include zen-grid-background();
+//   @include zen-layout(m) {
+//     @include zen-grid-background();
+//   }
+//   @include zen-layout(l) {
+//     @include zen-grid-background();
+//   }
+// }
+// ```
+//
+// Common usage:
+// ```
+// @include zen-grid-background();
+// ```
+//
+// $columns          = $zen-columns - The number of columns for this background. See the docs for [`$zen-columns`](section-grids.html#kssref-grids-variables-zen-columns).
+// $gutters          = $zen-gutters - The width of the gutters for this background. See the docs for [`$zen-gutters`](section-grids.html#kssref-grids-variables-zen-gutters).
+// $gutter-method    = $zen-gutter-method - The gutter method to use for this background. See the docs for [`$zen-gutter-method`](section-grids.html#kssref-grids-variables-zen-gutter-method).
+// $grid-width       = $zen-grid-width - The width of the entire grid for this background. See the docs for [`$zen-gutter-method`](section-grids.html#kssref-grids-variables-fixed-zen-grid-width).
+// $grid-color       = $zen-grid-color - The column color to use for the background grid image.
+// $grid-numbers     = $zen-grid-numbers - Specify the set of images used for the numbering of the columns in the background grid image.
+// $direction        = $zen-direction - The direction to use for this background. See the docs for [`$zen-direction`](section-grids.html#kssref-grids-variables-rtl-zen-direction).
+// $switch-direction = $zen-switch-direction - Whether to switch the default direction for this background. See the docs for [`$zen-switch-direction`](section-grids.html#kssref-grids-variables-rtl-zen-switch-direction).
+// $rtl-selector     = $zen-rtl-selector - The RTL selector for this background. See the docs for [`$zen-rtl-selector`](section-grids.html#kssref-grids-variables-rtl-zen-rtl-selector).
 //
 // Style guide: background.zen-grid-background
 @mixin zen-grid-background(

data/sass/zen-grids/_flow.scss

@@ -1,9 +1,17 @@
 // Flow module
 //
-// In your grid system, some HTML elements are grid containers and some HTML elements are grid items. Most of your content will be inside a grid item. According to CSS terminology, the unpositioned HTML elements inside a grid item are in the “normal flow” of a document.
-//
 // The "Flow" module for the Zen Grids system allows an item in the normal flow of a document to be aligned to the grid, e.g. an image can be aligned to the grid.
 //
+// To understand this module, it is important to understand the CSS definition of “normal flow”. According to CSS, all content is part of the [normal <em>flow</em>](http://www.w3.org/TR/CSS2/visuren.html#positioning-scheme) by default. For example, paragraph text and images are part of the normal flow.
+//
+// Positioned elements (floats, absolute positioning, etc.) are not part of the normal flow.
+//
+// Zen Grid’s grid items are also positioned elements and, therefore, are no longer part of the normal flow.
+//
+// For example, a layout designer will often make one of Zen Grid’s grid items span multiple columns. The elements within that grid item are part of the normal flow and span the same number of columns as their containing grid item. The layout designer may wish to have an element in the normal flow align to one or more of the columns within the grid item. For example, if a grid item spans 3 columns, the layout designer may want to have all of the images within it to align to the first column inside that grid item and have other flow items wrap around those images.
+//
+// Weight: -8
+//
 // Style guide: flow
 
 @import "./grids";
@@ -11,6 +19,12 @@
 
 // zen-flow-item-width()
 //
+// 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-span` to the number of columns that the parent element spans; fixed-unit layouts using px, em, etc. do not need to specify this.
+//
+// Unlike the `zen-grid-item()` mixin, this mixin does not float the HTML item; see the related `zen-float()` mixin. This mixin 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 `$direction` is set to `right` (for RTL languages), the alpha position is on the right and the omega position is on the left.
+//
 // Common usage:
 // ```
 // @include zen-flow-item-width(
@@ -42,25 +56,19 @@
 // );
 // ```
 //
-// 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-span` to the number of columns that the parent element spans; fixed-unit layouts using px, em, etc. do not need to specify this.
-//
-// Unlike the `zen-grid-item()` mixin, this mixin does not float the HTML item; see the related `zen-float()` mixin. This mixin 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 `$direction` is set to `right` (for RTL languages), the alpha position is on the right and the omega position is on the left.
-//
 // $column-span         - Required. The number of columns the flow item will span.
-// $parent-column-span  - Required for %-based layouts, but not for fixed-width layouts. The number of columns the parent grid item spans.
-// $alpha-gutter        - Whether the flow item should have a gutter on its left (or, for RTL layouts, on its right.) Defaults to `false`.
-// $omega-gutter        - Whether the flow item should have a gutter on its right (or, for RTL layouts, on its left.) Defaults to `true`.
-// $direction           - Defaults to `$zen-direction`
-// $columns             - Defaults to `$zen-columns`
-// $gutters             - Defaults to `$zen-gutters`
-// $gutter-method       - Defaults to `$zen-gutter-method`
-// $grid-width          - Defaults to `$zen-grid-width`
-// $box-sizing          - Defaults to `$zen-box-sizing`
-// $switch-direction    - Defaults to `$zen-switch-direction`
-// $rtl-selector        - Defaults to `$zen-rtl-selector`
-// $include-base        - Defaults to `$zen-auto-include-flow-item-base`
+// $parent-column-span  = false - Required for %-based layouts, but not for fixed-width layouts. The number of columns the parent grid item spans.
+// $alpha-gutter        = false - Whether the flow item should have a gutter on its left (or, for RTL layouts, on its right.)
+// $omega-gutter        = true - Whether the flow item should have a gutter on its right (or, for RTL layouts, on its left.)
+// $direction           = $zen-direction - The direction to use. See the docs for [`$zen-direction`](section-grids.html#kssref-grids-variables-rtl-zen-direction).
+// $columns             = $zen-columns - The number of columns in the grid. See the docs for [`$zen-columns`](section-grids.html#kssref-grids-variables-zen-columns).
+// $gutters             = $zen-gutters - The width of the gutters. See the docs for [`$zen-gutters`](section-grids.html#kssref-grids-variables-zen-gutters).
+// $gutter-method       = $zen-gutter-method - The gutter method to use. See the docs for [`$zen-gutter-method`](section-grids.html#kssref-grids-variables-zen-gutter-method).
+// $grid-width          = $zen-grid-width - The width of the entire grid. See the docs for [`$zen-gutter-method`](section-grids.html#kssref-grids-variables-fixed-zen-grid-width).
+// $box-sizing          = $zen-box-sizing - The box sizing to use. See the docs for [`$zen-box-sizing`](section-grids.html#kssref-grids-variables-zen-box-sizing).
+// $switch-direction    = $zen-switch-direction - Whether to switch the default direction. See the docs for [`$zen-switch-direction`](section-grids.html#kssref-grids-variables-rtl-zen-switch-direction).
+// $rtl-selector        = $zen-rtl-selector - The RTL selector for this background. See the docs for [`$zen-rtl-selector`](section-grids.html#kssref-grids-variables-rtl-zen-rtl-selector).
+// $include-base        = $zen-auto-include-flow-item-base - Whether to auto-include the zen-flow-item-base() mixin. See the docs for [`$zen-auto-include-flow-item-base`](section-flow.html#kssref-grids-variables-zen-auto-include-flow-item-base).
 //
 // Style guide: flow.zen-flow-item-width
 @mixin zen-flow-item-width(
@@ -224,19 +232,19 @@
 
 // zen-flow-item-base()
 //
+// Applies a standard set of properties to flow items that are aligned to the grid.
+//
 // Common usage:
 // ```
 // @include zen-flow-item-base();
 // ```
 //
-// Applies a standard set of properties to all flow items.
-//
-// $gutters          - Defaults to `$zen-gutters`
-// $gutter-method    - Defaults to `$zen-gutter-method`
-// $box-sizing       - Defaults to `$zen-box-sizing`
-// $direction        - Defaults to `$zen-direction`
-// $switch-direction - Defaults to `$zen-switch-direction`
-// $rtl-selector     - Defaults to `$zen-rtl-selector`
+// $gutters             = $zen-gutters - The width of the gutters. See the docs for [`$zen-gutters`](section-grids.html#kssref-grids-variables-zen-gutters).
+// $gutter-method       = $zen-gutter-method - The gutter method to use. See the docs for [`$zen-gutter-method`](section-grids.html#kssref-grids-variables-zen-gutter-method).
+// $box-sizing          = $zen-box-sizing - The box sizing to use. See the docs for [`$zen-box-sizing`](section-grids.html#kssref-grids-variables-zen-box-sizing).
+// $direction           = $zen-direction - The direction to use. See the docs for [`$zen-direction`](section-grids.html#kssref-grids-variables-rtl-zen-direction).
+// $switch-direction    = $zen-switch-direction - Whether to switch the default direction. See the docs for [`$zen-switch-direction`](section-grids.html#kssref-grids-variables-rtl-zen-switch-direction).
+// $rtl-selector        = $zen-rtl-selector - The RTL selector for this background. See the docs for [`$zen-rtl-selector`](section-grids.html#kssref-grids-variables-rtl-zen-rtl-selector).
 //
 // Style guide: flow.zen-flow-item-base
 @mixin zen-flow-item-base(
@@ -260,14 +268,20 @@
 //
 // Apply this to flow items that need to be floated.
 //
+// Using this mixin is longer than just typing `float: left;`. However, this mixin integrates with the RTL variables and mixins so that the direction of floating can be changed automatically.
+//
 // Common usage:
 // ```
 // @include zen-float();
 // ```
+// or:
+// ```
+// @include zen-float(right);
+// ```
 //
-// $direction        - Defaults to `$zen-direction`
-// $switch-direction - Defaults to `$zen-switch-direction`
-// $rtl-selector     - Defaults to `$zen-rtl-selector`
+// $direction           = $zen-direction - The direction to use. See the docs for [`$zen-direction`](section-grids.html#kssref-grids-variables-rtl-zen-direction).
+// $switch-direction    = $zen-switch-direction - Whether to switch the default direction. See the docs for [`$zen-switch-direction`](section-grids.html#kssref-grids-variables-rtl-zen-switch-direction).
+// $rtl-selector        = $zen-rtl-selector - The RTL selector for this background. See the docs for [`$zen-rtl-selector`](section-grids.html#kssref-grids-variables-rtl-zen-rtl-selector).
 //
 // Style guide: flow.zen-float
 @mixin zen-float(

data/sass/zen-grids/_functions.scss

@@ -2,6 +2,10 @@
 //
 // Helper functions for the Zen Grids mixins.
 //
+// This module contains many Sass functions that you may find useful in your style sheet. These functions are also used internally by all of the mixins in Zen Grids.
+//
+// Weight: 10
+//
 // Style guide: functions
 
 
@@ -23,9 +27,9 @@
 // }
 // ```
 //
-// $gutters - Defaults to `$zen-gutters`
-// $gutter-side - Defaults to `$zen-direction`
-// $direction - Defaults to `$zen-direction`
+// $gutters     = $zen-gutters - The width of the gutters. See the docs for [`$zen-gutters`](section-grids.html#kssref-grids-variables-zen-gutters).
+// $gutter-side = $zen-direction - The side of the grid item the gutter is needed for.
+// $direction   = $zen-direction - The direction to use. See the docs for [`$zen-direction`](section-grids.html#kssref-grids-variables-rtl-zen-direction).
 //
 // weight: -1
 //
@@ -78,10 +82,10 @@
 // }
 // ```
 //
-// $columns - Defaults to `$zen-columns`
-// $gutters - Defaults to `$zen-gutters`
-// $gutter-method - Defaults to `$zen-gutter-method`
-// $grid-width - Defaults to `$zen-grid-width`
+// $columns       = $zen-columns - The number of columns in the grid. See the docs for [`$zen-columns`](section-grids.html#kssref-grids-variables-zen-columns).
+// $gutters       = $zen-gutters - The width of the gutters. See the docs for [`$zen-gutters`](section-grids.html#kssref-grids-variables-zen-gutters).
+// $gutter-method = $zen-gutter-method - The gutter method to use. See the docs for [`$zen-gutter-method`](section-grids.html#kssref-grids-variables-zen-gutter-method).
+// $grid-width    = $zen-grid-width - The width of the entire grid. See the docs for [`$zen-gutter-method`](section-grids.html#kssref-grids-variables-fixed-zen-grid-width).
 //
 // weight: -1
 //
@@ -114,6 +118,8 @@
 
 // zen-grid-item-width()
 //
+// Calculates the width of a grid item that spans the specified number of columns.
+//
 // Common usage:
 // ```
 // .ex {
@@ -121,14 +127,12 @@
 // }
 // ```
 //
-// Calculates the width of a grid item that spans the specified number of columns.
-//
-// $column-span - Required. The number of columns to calculate the width of.
-// $columns - Defaults to `$zen-columns`
-// $gutters - Defaults to `$zen-gutters`
-// $gutter-method - Defaults to `$zen-gutter-method`
-// $grid-width - Defaults to `$zen-grid-width`
-// $box-sizing - Defaults to `$zen-box-sizing`
+// $column-span   - Required. The number of columns to calculate the width of.
+// $columns       = $zen-columns - The number of columns in the grid. See the docs for [`$zen-columns`](section-grids.html#kssref-grids-variables-zen-columns).
+// $gutters       = $zen-gutters - The width of the gutters. See the docs for [`$zen-gutters`](section-grids.html#kssref-grids-variables-zen-gutters).
+// $gutter-method = $zen-gutter-method - The gutter method to use. See the docs for [`$zen-gutter-method`](section-grids.html#kssref-grids-variables-zen-gutter-method).
+// $grid-width    = $zen-grid-width - The width of the entire grid. See the docs for [`$zen-gutter-method`](section-grids.html#kssref-grids-variables-fixed-zen-grid-width).
+// $box-sizing    = $zen-box-sizing - The box sizing to use. See the docs for [`$zen-box-sizing`](section-grids.html#kssref-grids-variables-zen-box-sizing).
 //
 // Style guide: functions.zen-grid-item-width
 @function zen-grid-item-width(
@@ -155,6 +159,8 @@
 
 // zen-direction-switch()
 //
+// Returns the opposite direction, given "left" or "right".
+//
 // Common usage:
 // ```
 // .ex {
@@ -162,26 +168,24 @@
 // }
 // ```
 //
-// weight: 1
-//
-// Returns the opposite direction, given "left" or "right".
+// $direction - Required. The direction you want to switch.
 //
-// $dir - Required. The direction you want to switch.
+// weight: 1
 //
 // Style guide: functions.zen-direction-switch
 @function zen-direction-switch(
-  $dir
+  $direction
 ) {
-  @if $dir == left {
+  @if $direction == left {
     @return right;
   }
-  @else if $dir == right {
+  @else if $direction == right {
     @return left;
   }
-  @else if $dir != none and $dir != both {
+  @else if $direction != none and $direction != both {
     @warn "Invalid direction passed to zen-direction-switch().";
   }
-  @return $dir;
+  @return $direction;
 }
 
 // zen-support-for-ie()

data/sass/zen-grids/_grids.scss

@@ -1,7 +1,10 @@
+// Grids module
 //
-// Main module for the Zen Grids system.
+// The “grids” module contains most of the configurable variables and mixins you’ll need to create a layout.
 //
-
+// Weight: -10
+//
+// Style guide: grids
 
 // Import the global variables needed by all of Zen Grids.
 @import "./variables";
@@ -14,7 +17,9 @@
 //
 // Since `$zen-rtl-selector` defaults to `false`, inline Right-To-Left language support is off by default.
 //
-// $selector - Defaults to $zen-rtl-selector.
+// $selector = $zen-rtl-selector - The RTL selector for this grid item. See the docs for [`$zen-rtl-selector`](section-grids.html#kssref-grids-variables-rtl-zen-rtl-selector).
+//
+// weight: 20
 //
 // Style guide: grids.zen-rtl
 
@@ -33,10 +38,33 @@
   }
 }
 
+// zen-grid-container()
 //
 // Apply this to create a grid container element.
-// @see http://next.zengrids.com/reference/grids/#zen-grid-container
 //
+// If this grid is nested inside another grid, the `$context` parameter can be used to align the nested grid with the parent grid. `$context` can be set to `none` (the default), `grid-item`, or `flow`.
+//
+// If the nested grid’s container is a child element of the parent grid’s grid item, set `$context: flow`.
+//
+// Otherwise, if the nested grid’s container is the same element as the parent grid’s grid item, set `$context: grid-item` and apply this mixin *after* the [`zen-grid-item()`](#kssref-grids-zen-grid-item) mixin is applied for the parent grid. This mixin removes any gutters on the container since the nested grid will have its own gutters.
+//
+// Common usage:
+// ```
+// @include zen-grid-container();
+// ```
+// or:
+// ```
+// @include zen-grid-container(grid-item);
+// ```
+//
+// $context            = none - If this grid is nested inside another grid, the `$context` parameter can be used to align the nested grid with the parent grid. It can be set to `none`, `grid-item`, or `flow`.
+// $gutters            = $zen-gutters - The width of the gutters for this container. See the docs for [`$zen-gutters`](section-grids.html#kssref-grids-variables-zen-gutters).
+// $gutter-method      = $zen-gutter-method - The gutter method to use for this container. See the docs for [`$zen-gutter-method`](section-grids.html#kssref-grids-variables-zen-gutter-method).
+// $direction          = $zen-direction - The direction to use for this container. See the docs for [`$zen-direction`](section-grids.html#kssref-grids-variables-rtl-zen-direction).
+// $switch-direction   = $zen-switch-direction - Whether to switch the default direction for this container. See the docs for [`$zen-switch-direction`](section-grids.html#kssref-grids-variables-rtl-zen-switch-direction).
+// $rtl-selector       = $zen-rtl-selector - The RTL selector for this container. See the docs for [`$zen-rtl-selector`](section-grids.html#kssref-grids-variables-rtl-zen-rtl-selector).
+//
+// Style guide: grids.zen-grid-container
 @mixin zen-grid-container(
   $context            : none,
   $gutters            : $zen-gutters,
@@ -107,9 +135,36 @@
   }
 }
 
+// zen-grid-item()
+//
+// 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.
+//
+// To make the grid item float from the right, set the `$direction` to `right`; it defaults to `left` (the value of `$zen-direction`.) For grid items that are floated right, the `$column-position` is counted from the right instead of from the left.
 //
-// Apply this to each grid item. @see http://next.zengrids.com/reference/grids/#zen-grid-item
+// Common usage:
+// ```
+// // The grid item spans 2 columns starting from the 3rd column from the left,
+// // e.g. It spans columns 3 and 4 counting from the left.
+// @include zen-grid-item($column-span: 2, $column-position: 3);
+// ```
+// or:
+// ```
+// // The grid item spans 2 columns starting from the 3rd column from the right,
+// // e.g. It spans columns 3 and 4 counting from the right.
+// @include zen-grid-item(2, 3, right);
+// ```
 //
+// $column-span        - Required. The number of columns the grid item will span.
+// $column-position    - Required. The column number the grid item starts on.
+// $direction          = $zen-direction - The floating direction to use for this grid item. See the docs for [`$zen-direction`](section-grids.html#kssref-grids-variables-rtl-zen-direction).
+// $gutters            = $zen-gutters - The width of the gutters for this grid item. See the docs for [`$zen-gutters`](section-grids.html#kssref-grids-variables-zen-gutters).
+// $gutter-method      = $zen-gutter-method - The gutter method to use for this grid item. See the docs for [`$zen-gutter-method`](section-grids.html#kssref-grids-variables-zen-gutter-method).
+// $box-sizing         = $zen-box-sizing - The box sizing to use for this grid item. See the docs for [`$zen-box-sizing`](section-grids.html#kssref-grids-variables-zen-box-sizing).
+// $switch-direction   = $zen-switch-direction - Whether to switch the default direction for this grid item. See the docs for [`$zen-switch-direction`](section-grids.html#kssref-grids-variables-rtl-zen-switch-direction).
+// $rtl-selector       = $zen-rtl-selector - The RTL selector for this grid item. See the docs for [`$zen-rtl-selector`](section-grids.html#kssref-grids-variables-rtl-zen-rtl-selector).
+// $include-base       = $zen-auto-include-grid-item-base - Whether to auto-include the zen-grid-item-base() mixin. See the docs for [`$zen-auto-include-grid-item-base`](section-grids.html#kssref-grids-variables-zen-auto-include-grid-item-base).
+//
+// Style guide: grids.zen-grid-item
 @mixin zen-grid-item(
   $column-span,
   $column-position,
@@ -175,10 +230,27 @@
   }
 }
 
+// zen-grid-item-base()
+//
+// Applies a standard set of properties for grid items in the layout.
+//
+// See the documentation for the [`$zen-auto-include-grid-item-base`](#kssref-grids-variables-zen-auto-include-grid-item-base) and [`$zen-auto-include-flow-item-base`](section-flow.html#kssref-flow-variables-zen-auto-include-flow-item-base) variables for when to use this mixin.
+//
+// Common usage:
+// ```
+// @include zen-grid-item-base();
+// ```
+//
+// $gutters            = $zen-gutters - The width of the gutters for this grid item. See the docs for [`$zen-gutters`](section-grids.html#kssref-grids-variables-zen-gutters).
+// $gutter-method      = $zen-gutter-method - The gutter method to use for this grid item. See the docs for [`$zen-gutter-method`](section-grids.html#kssref-grids-variables-zen-gutter-method).
+// $box-sizing         = $zen-box-sizing - The box sizing to use for this grid item. See the docs for [`$zen-box-sizing`](section-grids.html#kssref-grids-variables-zen-box-sizing).
+// $direction          = $zen-direction - The floating direction to use for this grid item. See the docs for [`$zen-direction`](section-grids.html#kssref-grids-variables-rtl-zen-direction).
+// $switch-direction   = $zen-switch-direction - Whether to switch the default direction for this grid item. See the docs for [`$zen-switch-direction`](section-grids.html#kssref-grids-variables-rtl-zen-switch-direction).
+// $rtl-selector       = $zen-rtl-selector - The RTL selector for this grid item. See the docs for [`$zen-rtl-selector`](section-grids.html#kssref-grids-variables-rtl-zen-rtl-selector).
 //
-// Applies a standard set of properites for grid items in the layout.
-// @see http://next.zengrids.com/reference/grids/#zen-grid-item-base
+// weight: 10
 //
+// Style guide: grids.zen-grid-item-base
 @mixin zen-grid-item-base(
   $gutters            : $zen-gutters,
   $gutter-method      : $zen-gutter-method,
@@ -235,10 +307,24 @@
   }
 }
 
+// zen-new-row()
 //
 // Apply this to a grid item so that it starts a new row.
-// @see http://next.zengrids.com/reference/grids/#zen-new-row
 //
+// Common usage:
+// ```
+// @include zen-new-row();
+// ```
+// or:
+// ```
+// @include zen-new-row(right);
+// ```
+//
+// $clear             = $zen-direction - The floating direction to use for this grid item. See the docs for [`$zen-direction`](section-grids.html#kssref-grids-variables-rtl-zen-direction).
+// $switch-direction  = $zen-switch-direction - Whether to switch the default direction for this grid item. See the docs for [`$zen-switch-direction`](section-grids.html#kssref-grids-variables-rtl-zen-switch-direction).
+// $rtl-selector      = $zen-rtl-selector - The RTL selector for this grid item. See the docs for [`$zen-rtl-selector`](section-grids.html#kssref-grids-variables-rtl-zen-rtl-selector).
+//
+// Style guide: grids.zen-new-row
 @mixin zen-new-row(
   $clear              : $zen-direction,
   $switch-direction   : $zen-switch-direction,
@@ -257,10 +343,23 @@
   }
 }
 
+// zen-apply-gutter-padding()
 //
 // Applies the gutter to a grid item when using the padding gutter method.
-// @see http://next.zengrids.com/reference/grids/#zen-apply-gutter-padding
 //
+// Common usage:
+// ```
+// @include zen-apply-gutter-padding();
+// ```
+//
+// $gutters           = $zen-gutters - The width of the gutters. See the docs for [`$zen-gutters`](section-grids.html#kssref-grids-variables-zen-gutters).
+// $direction         = $zen-direction - The floating direction to use. See the docs for [`$zen-direction`](section-grids.html#kssref-grids-variables-rtl-zen-direction).
+// $switch-direction  = $zen-switch-direction - Whether to switch the default direction. See the docs for [`$zen-switch-direction`](section-grids.html#kssref-grids-variables-rtl-zen-switch-direction).
+// $rtl-selector      = $zen-rtl-selector - The RTL selector. See the docs for [`$zen-rtl-selector`](section-grids.html#kssref-grids-variables-rtl-zen-rtl-selector).
+//
+// weight: 30
+//
+// Style guide: grids.zen-apply-gutter-padding
 @mixin zen-apply-gutter-padding(
   $gutters            : $zen-gutters,
   $direction          : $zen-direction,