compass-lucid-grid 0.3.0 → 0.4.0

data/README.md

@@ -1,41 +1,268 @@
-#The Lucid Grid
+#Lucid: A _smarter_ CSS grid for Compass
 
-Currently in early development. The API is still evolving, but feel free to give it a try. Comments/suggestions welcome!
+###Philosophy and Killer Features
 
-###Lucid is for developers who:
+CSS grids make web development easier... except when they don't. 
 
-* Like lean stylesheets. 
-* Think using "alpha" and "omega" is a hacky solution.
-* Hate fighting with gutters to get their layouts aligned.
-* Want to apply borders and padding to grid elements without wrapping `<div>`s.
-* Want a grid that plays nice with @media queries. 
+Wrapping `<div>`s, `.alpha` `.omega` madness, and fighting with gutters to get layouts aligned... These are the compromises that developers are forced live with.
 
-###Developer's Notes:
+But NOT anymore. Lucid makes full use of [SASS](http://sass-lang.com/) and [Compass](http://compass-style.org/) in order to make CSS grids sane again.
 
-* Lucid uses @extend internally to prevent the CSS duplication that can happen with too many @includes.
-* Lucid allow you to adjust the width of grid element via a mixin parameter.
-* Full documenation coming soon.
-* MIT License
+Not only does it match other grids in functionality, but it also comes with a handful of unique features:
 
-###Try it out:
+* Adjust grid dimensions / number of columns instantly through variables (as with all SASS grids)
+* Add borders and padding _directly to your grid elements_ without using nested `<div>`s
+* Use "gutterless" grid elements for nesting and precise styling
+* Cater to multiple screen widths by reconfiguring Lucid inside media queries
+* Achieve leaner compiled CSS than other SASS grids, due to Lucid's internal [@extend](http://sass-lang.com/docs/yardoc/file.SASS\_REFERENCE.html#extend) logic
 
-```
+Go ahead! Judge for yourself:
+
+#Installation
+
+```bash
 (sudo) gem install compass-lucid-grid
 compass help -r lucid lucid
 ```
 
-THEN
+Then
 
-```
+```bash
 cd your_existing_project
 echo "require 'lucid'" >> config.rb
-compass install -r lucid lucid`
+compass install -r lucid lucid
 ```
 
-OR
+Or
 
-```
+```bash
 compass create -r lucid --using lucid your_new_project
 ```
 
-(Note: Creating a project with Lucid does not generate the default Compass stylesheets, only the `_grid.scss` partial.)
+(Note: Creating a project with Lucid does not generate the default Compass stylesheets, only the `\_grid.scss` partial.)
+
+#Documentation
+
+###Setup 
+
+After installation, @include '_grid.scss' or copy its contents into your base file. It should look something like this:
+
+```scss
+// Remove the following line if Compass has already been included
+@import "compass/utilities/general/clearfix";
+
+// Grid dimensions
+$grid-width: 990px;
+$grid-columns: 12;
+
+// The amount of margin to apply to each side of a grid element
+$grid-gutter: 15px;
+
+// The distance between the grid container and the first grid element
+$grid-outer-gutter: 15px;
+
+// Use "pie-clearfix", "overflow", or "none"?
+$grid-clearfix: "pie-clearfix";
+
+// Center rows?
+$grid-centering: true;
+
+// Include Lucid
+@import 'lucid';
+
+// Output 4 CSS classes that Lucid uses as @extend "hooks"
+@include grid-init;
+```
+
+### Basic Usage
+
+Now we're ready to style:
+
+```scss
+/* SCSS */
+
+.container {
+  @include container;     // defines grid container
+  background: blue;
+
+  .sidebar {
+    @include columns(3);  // 3 column element
+  }
+
+  .main {
+    @include columns(9);  // 9 column element
+  }
+}
+
+.another-container {
+  @include container;     // yet another container
+  background: red;
+}
+
+
+/* Compiled CSS */
+
+.grid-container,
+.container,
+.another-container {
+  // container styles
+}
+
+.grid-clearfix,
+.grid-container,
+.container,
+.another-container {
+  // clearfix styles
+}
+
+.container {
+  background: blue;
+}
+
+.another-container {
+  background: red;
+}
+
+.grid-element,
+.container .sidebar,
+.container .main {
+  // float: left, display: inline, and styles common to all grid elements
+}
+
+.container .sidebar {
+  // 3 column width
+}
+
+.container .main {
+  // 3 column width
+}
+```
+
+Did you get that?
+
+Instead of applying styles directly to each grid element, whenever possible, Lucid groups grid selectors that contain the same styles.
+
+This results in MUCH leaner compiled CSS, as it avoids needless repetition.
+
+###Using with Borders and Padding
+
+With other grids, styling an inner `<div>` is often the cleanest method to accomodate borders and padding, since it preserves the width of the grid element:
+
+```html
+<div class="container">
+  <div class="wrapper">
+    <div class="safe-to-style">
+      <!-- content -->
+    </div>
+  </div>
+</div>
+```
+
+```scss
+.wrapper {
+  // grid float, width, styles
+}
+
+.safe-to-style {
+  border: 1px solid #ccc;
+  padding: 19px;
+}
+```
+
+With Lucid, this practice is no longer necessary, as you can adjust the width of grid elements individually! Just add your total borders / padding together and pass it as a mixin parameter. Like this:
+
+```html
+<div class="container">
+  <div class="look-ma-no-wrapper">
+    <!-- content -->
+  </div>
+</div>
+```
+
+```scss
+.look-ma-no-wrapper {
+  @include columns(3, 40px);  // (1px + 19px) * 2
+
+  border: 1px solid #ccc;
+  padding: 19px;
+}
+```
+
+Note, adjusting the width of a grid element means that nesting other grid elements within is no longer guaranteed to add up correctly. You *can* make use of Lucid's `+grid-reinit` to define a new inner grid however!
+
+###Gutterless Elements
+
+Sometimes, it's convenient to have grid units without gutters. For example, when you want to nest elements within other elements:
+
+```scss
+.gutterless {
+  @include columns(9, 0, false);
+
+  .nested {
+    @include column(3);
+  }
+
+  .also-nested {
+    @include column(6);
+  }
+}
+```
+
+#Advanced
+
+###Adapting to Media Queries
+
+Lucid uses pixels, which means that it's a fixed-width grid (percentages aren't precise enough). Fortunately, this doesn't mean that your sites have to be fixed-width:
+
+```scss
+@include grid-init;
+
+// full width grid
+.container { @include container; }
+.sidebar { @include column(3); }
+.main { @include column(9); }
+
+@media screen and (max-width: 480px) {
+
+  // redeclare one or more variables
+  $grid-width: 480px;
+
+  // outputs a single modified @extend hook
+  @include grid-reinit;
+  
+  // same proportions as before, just smaller!
+  .container { @include container; }
+  .sidebar { @include column(3); }
+  .main { @include column(9); }
+
+}
+```
+
+###Modifying @extend Hooks
+
+As mentioned before, Lucid used @extend internally to achieve leaner stylesheets. In order to do this, `+grid-init` outputs four benign classes for @extend to "hook" onto. These classes can be modified (defaults shown):
+
+```scss
+$grid-hook-clearfix: ".grid-clearfix";
+$grid-hook-container: ".grid-container";
+$grid-hook-element: ".grid-element";
+$grid-hook-gutterless: ".grid-column-gutterless";
+```
+
+###Unsemantic Class Names
+
+For testing purposes, or for those who are unwilling to part with old ways, Lucid provides a class name generator mixin:
+
+```scss
+// where # is the number of columns
+
+// outputs .g1 => .g#
+@include grid-classes;
+
+// outputs gutterless classes in addition (.gl1 => .gl#);
+@include grid-classes(true);
+
+// changes the class prefixes (outputs .grid-1 => .grid-# and .gutterless-1 => .gutterless-#)
+@include grid-classes(true, 'grid-', 'gutterless-');
+```
+

data/stylesheets/_lucid.scss

@@ -2,27 +2,29 @@
 //
 // THE LUCID GRID | SETUP
 // plugin by Yifei Zhang [http://yifei.co]
+// MIT License [https://github.com/ezYZ/lucid/blob/master/LICENSE.txt]
 // 
 //============================================================================//
 
 // Grid configuration 
-$grid-width: 960px !default;
+$grid-width: 990px !default;
 $grid-columns: 12 !default;
 $grid-gutter: 15px !default;
-$grid-outer-gutter: 30px !default;
+$grid-outer-gutter: 15px !default;
 
-// @extend hook class names
-$grid-hook-container: ".lucid-grid" !default;
-$grid-hook-row: ".lucid-row" !default;
-$grid-hook-column: ".lucid-column" !default;
-$grid-hook-gutterless: ".lucid-gutterless" !default;
-
-// Use "pie-clearfix" clearfix or "overflow" clearfix?
+// Use "pie-clearfix", "overflow", or "none"?
 $grid-clearfix: "pie-clearfix" !default;
 
 // Center rows by default?
 $grid-centering: true !default;
 
+// @extend hook selectors
+$grid-hook-clearfix: ".grid-clearfix" !default;
+$grid-hook-container: ".grid-container" !default;
+$grid-hook-element: ".grid-element" !default;
+$grid-hook-gutterless: ".grid-column-gutterless" !default;
+
+
 //
 // Imports
 //

data/stylesheets/lucid/_internal.scss

@@ -2,65 +2,89 @@
 //
 // THE LUCID GRID | INTERNAL MIXINS
 // plugin by Yifei Zhang [http://yifei.co]
+// MIT License [https://github.com/ezYZ/lucid/blob/master/LICENSE.txt]
 // 
 //============================================================================//
 
-// Calculate the base grid "unit"
-$grid-outer-padding: $grid-outer-gutter - $grid-gutter;
-$grid-inner-width: $grid-width - (2 * $grid-outer-padding);
-$gu: $grid-inner-width / $grid-columns;
 
+//
+// Grid Clearfix
+// - sets preferred clearfix method
+// - uses +clearfix or +pie-clearfix
+//
+// $clearfix  (string/bool)  type of clearfix to use ("pie-clearfix", "overflow", false)
+//
+
+@mixin _grid-clearfix($clearfix) {
+  @if $clearfix == 'overflow' {
+    @include clearfix;
+  }
+  @else {
+    @include pie-clearfix;
+  }
+}
+
+
+//
 // Grid Container
-// Applies the grid width and centering
-@mixin _grid-container($centered: $grid-centering, $width: $grid-inner-width) {
+// - applies container width and options
+// - used by the .grid-container @extend hook
+//
+// $clearfix  (string/bool)   type of clearfix to use ("pie-clearfix", "overflow", false)
+// $centered  (bool)          whether to apply centering margins
+// $outer     (px)            calculated width of container padding
+// $width     (px)            calculated width of grid
+//
+
+@mixin _grid-container($clearfix, $centered, $outer, $width) {
+  @if $clearfix != false {
+    @extend #{$grid-hook-clearfix};
+  }
+
   @if $centered == true {
     margin-left: auto;
     margin-right: auto;
   }
-  
-  padding-left: $grid-outer-padding;
-  padding-right: $grid-outer-padding;
+
+  @if $outer > 0 {
+    padding-left: $outer;
+    padding-right: $outer;
+  }
 
   width: $width;
 }
 
-// Grid Rows
-// Centered to create outer gutter appearance
-// Applies clearfix (to contain floats)
-@mixin _grid-row($clearfix) {
-  margin-left: auto;
-  margin-right: auto;
 
-  @if $clearfix == overflow {
-    @include clearfix;
-  } @else {
-    @include pie-clearfix;
-  }
-}
+//
+// Grid Element
+// - applies shared grid element styles
+// - used in .grid-element and .grid-gutterless @extend hooks
+//
+// $gutter  (px)  whether to include gutters
+//
 
-// Styles shared by all grid elements
-// Optionally include gutter
 @mixin _grid-element($gutter) {
   display: inline;
   float: left;
 
   @if $gutter > 0 {
-    margin-left: $grid-gutter;
-    margin-right: $grid-gutter;
+    margin-left: $gutter;
+    margin-right: $gutter;
   }
 }
 
-// Individual styles for each grid element
-@mixin _grid-element-style($columns, $offset, $gutter, $adjustment) {
 
-  // Shift element left or right with +/- $offset
-  @if $offset > 0 {
-    margin-left: ($offset * $gu) + $gutter;
-  } @else if $offset < 0 {
-    margin-left: ($offset * $gu) - $gutter;
-  }
+//
+// Grid Element Style
+// - applies individual styles for each grid element
+//
+// $columns     (int)   number of columns to span
+// $adjustment  (px)    width to shrink the element by (to compensate for borders and padding)
+// $gutter      (px)    width of gutter
+// $col-width   (px)    calculated width of a single grid column
+//
 
-  // Adjust element width 
-  width: ($columns * $gu) - $adjustment - ($gutter * 2);
+@mixin _grid-element-style($columns, $adjustment, $gutter, $col-width) {
+  width: ($columns * $col-width) - $adjustment - ($gutter * 2);
 }
 

data/stylesheets/lucid/_public.scss

@@ -2,72 +2,153 @@
 //
 // THE LUCID GRID | PUBLIC MIXINS
 // plugin by Yifei Zhang [http://yifei.co]
+// MIT License [https://github.com/ezYZ/lucid/blob/master/LICENSE.txt]
 // 
 //============================================================================//
 
-// Generate @extend hooks
-@mixin grid-hooks {
-  #{$grid-hook-container} { @include _grid-container; }
-  #{$grid-hook-row} { @include _grid-row($grid-clearfix); }
-  #{$grid-hook-column} { @include _grid-element($grid-gutter); }
-  #{$grid-hook-gutterless} { @include _grid-element(0); }
+
+//
+// GRID CALCULATIONS
+//----------------------------------------------------------------------------//
+
+
+// The difference between outer and inner gutters
+@function grid-outer-padding() {
+  @return $grid-outer-gutter - $grid-gutter;
+}
+
+// The actual width that contains the grid
+@function grid-actual-width() {
+  @return $grid-width - (2 * ($grid-outer-gutter - $grid-gutter));
+}
+
+// The full width of a single column
+@function grid-column-width() {
+  @return ($grid-width - (2 * ($grid-outer-gutter - $grid-gutter))) / $grid-columns;
 }
 
 //
-// Grid Mixins
+// GRID BASIC USAGE
+//----------------------------------------------------------------------------//
+
+
+//
+// Grid Init
+// - outputs 4 CSS selectors for use as @extend "hooks"
+// - (required) must appear before other grid mixins
 //
 
+@mixin grid-init {
+  @if $grid-clearfix != 'none' {
+    #{$grid-hook-clearfix} { @include _grid-clearfix($grid-clearfix); }
+  }
+  #{$grid-hook-container} { @include _grid-container($grid-clearfix, $grid-centering, grid-outer-padding(), grid-actual-width()); }
+  #{$grid-hook-element} { @include _grid-element($grid-gutter); }
+  #{$grid-hook-gutterless} { @include _grid-element(0); }
+}
+
+
+//
 // Container
-@mixin grid {
+// - adds selector to .grid-container and .grid-clearfix hooks
+// - apply to the parent(s) of all floated grid elements
+//
+
+@mixin container {
   @extend #{$grid-hook-container};
 }
 
-// Row
-@mixin row {
-  @extend #{$grid-hook-row};
-}
 
-// Element (with gutters)
-@mixin col($columns, $offset: 0, $width-adjustment: 0) {
-  @extend #{$grid-hook-column};
-  @include _grid-element-style($columns, $offset, $grid-gutter, $width-adjustment);
-}
+//
+// Columns
+// - defines a grid element that spans one or more columns 
+//
+// $columns     (int)   number of columns to span
+// $adjustment  (px)    amount to shrink width (to compensate for borders and padding)
+// $gutters     (bool)  whether to include gutters
+//
 
-// Element (without gutters)
-@mixin col-gutterless($columns, $offset: 0, $width-adjustment: 0) {
-  @extend #{$grid-hook-gutterless};
-  @include _grid-element-style($columns, $offset, 0, $width-adjustment);
+@mixin columns($columns, $adjustment: 0, $gutters: true) {
+  @if $gutters == false { 
+    @extend #{$grid-hook-gutterless};
+    @include _grid-element-style($columns, $adjustment, 0, grid-column-width());
+  }
+  @else {
+    @extend #{$grid-hook-element};
+    @include _grid-element-style($columns, $adjustment, $grid-gutter, grid-column-width());
+  }
 }
 
-// Element (without width, with gutters)
-// Useful for aligning headers, orphans, etc.
-@mixin col-widthless {
-  @extend #{$grid-hook-column};
+
+//
+// GRID ELEMENT MODIFIERS
+//----------------------------------------------------------------------------//
+
+
+//
+// Row Break
+// - breaks grid element into a new row
+//
+// $clear   (string)  direction to clear ("left", "both")
+//
+
+@mixin row-break($clear: 'left') {
+  clear: unquote($clear);
 }
 
+
 //
-// Experimental Media Query Adjustments
+// Offset
+// - shifts grid element to the left/right (-/+) by one or more columns
+// - must be defined after +column
+// 
+// $offset    (int)   the number of columns to shift (positive to the right, negative to the left)
+// $gutters   (bool)  whether the element has gutters
+//
+
+@mixin offset($offset, $gutters: true) {
+  $gutter: if($gutters == false, 0, $grid-gutter);
+
+  margin-left: ($offset * grid-column-width()) + $gutter;
+}
+
+
 //
+// Other / Experimental
+//----------------------------------------------------------------------------//
+
 
-@mixin grid-adjustment($columns) {
-  $new-width: ($columns * $gu) - ($grid-outer-padding * 2);
+//
+// Grid Reinit
+// - outputs a modified .grid-container @extend hook for use within media queries, etc.
+// - must come after redeclaration of one or more grid configuration variables
+//   ($grid-width, $grid-columns, $grid-gutter, $grid-outer-gutter)
+// - does not redeclare clearfix, centering, or .grid-element hooks
+//
 
-  #{$grid-hook-container} { @include _grid-container(false, $new-width); }
+@mixin grid-reinit {
+  #{$grid-hook-container} { @include _grid-container(false, false, grid-outer-padding(), grid-actual-width()); }
 }
 
 //
-// Generate Non-semantic Classes
+// Grid Classes
+// - outputs a set of classes for use in markup
+// - new rows require `clear: left;` to be added manually
+// - not recommended under most circumstances
+//
+// $gutterless          (bool)    whether to output gutterless grid element classes
+// $prefix              (string)  class name prefix for grid elements
+// $gutterless-prefix   (string)  class name prefix for gutterless grid elements
 //
 
 @mixin grid-classes($gutterless: false, $prefix: 'g', $gutterless-prefix: 'gl') {
   @for $i from 1 through $grid-columns {
-    .#{$prefix}#{$i} { @include col($i); }
+    .#{$prefix}#{$i} { @include columns($i); }
   }
 
-  @if $gutterless != false {
+  @if $gutterless == true {
     @for $i from 1 through $grid-columns {
-      .#{$gutterless-prefix}#{$i} { @include col-gutterless($i); }
+      .#{$gutterless-prefix}#{$i} { @include columns($i, 0, false); }
     }
   }
 }
-

data/templates/project/_grid.scss

@@ -2,52 +2,35 @@
 // 
 // THE LUCID GRID | QUICKSTART
 // plugin by Yifei Zhang [http://yifei.co]
+// MIT License [https://github.com/ezYZ/lucid/blob/master/LICENSE.txt]
 //
 // @import this into your project or paste into your base/bootstrap file 
 //
 //============================================================================//
 
-//
-// Configuration and Initialization
-//
-// Already have Compass @imported? Go ahead and remove `clearfix`.
-//
-// Configuration $variables should be defined before Lucid is @imported. 
-// View the full list of options and defaults at [http://yifei.co/lucid]
-//
 
+// Remove the following line if Compass has already been included
 @import "compass/utilities/general/clearfix";
-@import 'lucid';
 
-//
-// @Extend Hooks (Required)
-//
-// Lucid uses SASS's @extend (internally!) in order to produce leaner compiled 
-// stylesheets*. The `grid-hooks` mixin generates four base classes that are 
-// reused by Lucid's other mixins through @extend.
-//
-// * @include misused leads to fat, repetative stylesheets. Lucid knows better.
-//
+// Grid dimensions
+$grid-width: 990px;
+$grid-columns: 12;
 
-@include grid-hooks;
+// The amount of margin to apply to each side of a grid element
+$grid-gutter: 15px;
+
+// The distance between the grid container and the first grid element
+$grid-outer-gutter: 15px;
+
+// Use "pie-clearfix", "overflow", or "none"?
+$grid-clearfix: "pie-clearfix";
+
+// Center rows?
+$grid-centering: true;
+
+// Include Lucid
+@import 'lucid';
+
+// Output 4 CSS classes that Lucid uses as @extend "hooks"
+@include grid-init;
 
-//============================================================================//
-//
-// BASIC USAGE
-// For the full docs, visit [http://yifei.co/lucid]
-//
-// @include grid;                   // setup a new grid container
-// @include row;                    // setup a new grid row 
-//
-// @include col(3);                 // grid element that spans 3 columns
-// @include col(3, 2);              // shifted 2 columns to right
-// @include col(3, 2, 20px);        // subtract 20px from `width` to adjust for borders/padding
-// @include col-gutterless(5, 2);   // "gutterless" element, identical usage to `col()`
-// @include col-widthless;          // adds float and gutters only (useful for aligning headers, etc.)
-//
-// @include grid-classes;           // generate .g* classes to use in markup
-// @include grid-classes(true);     // generate .g* and .gl* (gutterless) classes
-//
-// @include grid-adjustment($n);    // reduce container to $n columns (width)
-//
-//============================================================================//

data/templates/project/manifest.rb

@@ -1,4 +1,4 @@
-description "A Compass/SASS grid for people who love semantics."
+description "A Compass/SASS grid for devs who care about semantics."
 
 discover :all
 
@@ -6,35 +6,15 @@ help %Q{
 
 ***
 
-THE LUCID GRID | HELP
-
-SETUP
-
-  @import 'lucid'
-  @include grid-hooks;             // generate @extend hooks 
-
-
-BASIC USAGE
-
-  @include grid;                   // setup a new grid container
-  @include row;                    // setup a new grid row 
-
-  @include col(3);                 // grid element that spans 3 columns
-  @include col(3, 2);              // shifted 2 columns to right
-  @include col(3, 2, 20px);        // subtract 20px from `width` to adjust for borders/padding
-  @include col-gutterless(5, 2);   // "gutterless" element, identical usage to `col()`
-  @include col-widthless;          // adds float and gutters only (useful for aligning headers, etc.)
+THE LUCID GRID
+plugin by Yifei Zhang [http://yifei.co]
 
-  @include grid-classes;           // generate .g* classes to use in markup
-  @include grid-classes(true);     // generate .g* and .gl* (gutterless) classes
+A smarter CSS grid for Compass.
 
-  @include grid-adjustment($n);    // reduce container to $n columns (width)
+For detailed documentation and examples, visit [https://github.com/ezYZ/lucid]
 
 ***
 
-For the full docs, visit [http://yifei.co/lucid]
-To view the source, visit [https://github.com/ezYZ/lucid]
-
 }
 
 welcome_message %Q{
@@ -42,15 +22,11 @@ welcome_message %Q{
 ***
 
 THE LUCID GRID
-plugin by Yifei Zhang
-
-Congrats! Your project templating life is about to become a lot saner.
+plugin by Yifei Zhang [http://yifei.co]
 
-For examples and documentation, visit:
-http://yifei.co/lucid
+A smarter CSS grid for Compass.
 
-Contribute on GitHub: 
-https://github.com/ezYZ/lucid
+For detailed documentation and examples, visit [https://github.com/ezYZ/lucid]
 
 ***
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: compass-lucid-grid
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-05-23 00:00:00.000000000Z
+date: 2011-06-04 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: compass
-  requirement: &86520450 !ruby/object:Gem::Requirement
+  requirement: &74705840 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: '0.11'
   type: :runtime
   prerelease: false
-  version_requirements: *86520450
+  version_requirements: *74705840
 description: A Compass/SASS grid that outputs lean, semantic stylesheets. Avoids CSS
   repetition on SASS compilation and reduces the need for wrapper <div>s.
 email: yz@yifei.co