compass-lucid-grid 0.5.0 → 0.5.1

data/README.md

@@ -1,24 +1,28 @@
 #Lucid: A _smarter_ CSS grid for Compass
 
-###Philosophy and Killer Features
+###Philosophy
 
-CSS grids make web development easier... except when they don't. 
+CSS grids make web development easier... except when they don't. Wrapping `<div>`s, `.alpha` `.omega` madness, and fighting with gutters to get layouts aligned... These are the compromises that developers are forced live with.
 
-Wrapping `<div>`s, `.alpha` `.omega` madness, and fighting with gutters to get layouts aligned... These are the compromises that developers are forced live with.
+Lucid is an effort to make CSS grids _sane_ again by taking full advantage of [SASS](http://sass-lang.com/) and [Compass](http://compass-style.org/).
 
-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.
+###The Basics
 
-Not only does it match other grids in functionality, but it also comes with a handful of unique features:
+* Configure grid dimensions / columns instantly through variables
+* Fixed width (`px` based) for finer control
+* Tested in IE6+, Chrome, FF
 
-* 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
+###The Specifics
+
+* Add borders and padding _directly to your grid elements_ without using nested `<div>`s or ugly overrides
 * Use "gutterless" grid elements for nesting and precise styling
-* Cater to multiple screen widths by reconfiguring Lucid inside media queries
+* Create new rows without wrapping `<div>`s
+* Cater to multiple screen widths by initializing new grid dimensions within 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:
+#Documentation
 
-#Installation
+##Installation
 
 ```bash
 (sudo) gem install compass-lucid-grid
@@ -33,19 +37,9 @@ echo "require 'lucid'" >> config.rb
 compass install -r lucid lucid
 ```
 
-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.)
-
-#Documentation
-
-###Setup `+grid-init` 
+##Setup `+grid-init` 
 
-After installation, @import '_grid.scss' or copy its contents into your base file. It should look something like this:
+After installation, `@import` \_grid.scss or copy its contents into your base file. Defaults (safe to remove) are shown below:
 
 ```scss
 // Remove the following line if Compass has already been included
@@ -74,23 +68,25 @@ $grid-centering: true;
 @include grid-init;
 ```
 
-###Basic Usage `+container, +columns( $columns (int) )` 
+##Basic Layout `+container, +columns( $columns (int) )` 
 
-Now we're ready to style:
+Now we're ready to style. All you need is a grid container and its child elements to start.
+
+Note: Instead of applying repetative styles directly to each and every element, Lucid groups selectors that contain the same styles. This results in MUCH leaner compiled CSS.
 
 ```scss
 /* SCSS */
 
-.container {
-  @include container;     // defines grid container
+.blue-box {
+  @include container;     // container element to "contain" child elements
   background: blue;
 
   .sidebar {
-    @include columns(3);  // 3 column element
+    @include columns(4);  // 4 column element (1/3 row)
   }
 
   .main {
-    @include columns(9);  // 9 column element
+    @include columns(8);  // 8 column element (2/3 row)
   }
 
   .custom {
@@ -99,114 +95,71 @@ Now we're ready to style:
   }
 }
 
-.another-container {
-  @include container;     // yet another container
+.red-box {
+  @include container;     // multiple containers are fine and dandy
   background: red;
 }
 
 
 /* Compiled CSS */
 
-.grid-container,
-.container,
-.another-container {
-  // container styles
+.grid-clearfix:after,     // clearfix styles
+.grid-container:after,
+.blue-box:after,
+.red-box:after {
+  content: "";
+  display: table;
+  clear: both;
 }
 
-.grid-clearfix,
-.grid-container,
-.container,
-.another-container {
-  // clearfix styles
+.grid-container,          // shared container styles
+.blue-box,
+.red-box {
+  margin-left: auto;
+  margin-right: auto;
+  width: 990px;
 }
 
-.container {
+.blue-box {               // unique container styles
   background: blue;
 }
 
-.another-container {
+.red-box {
   background: red;
 }
 
-.grid-element,
-.container .sidebar,
-.container .main,
-.container .custom {
-  // styles shared by all grid elements
+.grid-element,            // shared grid element styles
+.blue-box .sidebar,
+.blue-box .main,
+.blue-box .custom {
+  display: inline;
+  float: left;
+  margin-left: 15px;
+  margin-right: 15px;
 }
 
-.container .sidebar {
-  // 3 column width
+.blue-box .sidebar {      // 4 column width
+  width: 300px; 
 }
 
-.container .main {
-  // 9 column width
+.blue-box .main {         // 8 column width
+  width: 630px;
 }
 
-.container .custom {
-  width: 123px;       // custom width
+.blue-box .custom {       // custom width
+  width: 123px;
 }
 ```
 
-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.
+##Adjusting for Borders and Padding `+columns( $columns (int), $adjustment (px) )`
 
-###Offset Positioning `+offset( $offset (int), $gutters (0 || none) )`
+Grids typically don't play nice with borders and padding - these properties affect the width of elements, causing layouts to break. Using a wrapping `<div>` was often the cleanest method to accomodate styling.
 
-Sometimes, your layout needs a little bit of whitespace. Not a problem with Lucid:
-
-```scss
-.offset-to-the-right {
-  @include columns(6);
-  @include offset(3);         // shifts element to the right 3 columns
-}
-
-.offset-to-the-left {
-  @include columns(6);
-  @include offset(-3);        // shifts element to the left 3 columns
-}
-
-.offset-gutterless {
-  @include columns(6, 0, none);
-  @include offset(3, none);   // include 'none' or '0' when grid element is gutterless
-}
-```
-
-Unlike other grids that use padding or relative positioning to achieve this, Lucid does it with just `margin-left`. That means the element itself can still safely recieve styling!
-
-###New Rows `+row-break`
-
-Because of the way Lucid was designed, elements that exceed the width of the container will automatically wrap into the next row. If you want to insert a "row break" manually, it's dead simple:
-
-```scss
-.container {
-  @include container;       // 12 column container
-                            // would normally accomodate all 4 children
-  .on-row-1 {
-    @include columns(3);
-  }
-
-  .also-on-row-1 {
-    @include columns(3);
-  }
-
-  .on-row-2 {
-    @include columns(3);    // would have been on row 1
-    @include row-break;     // +row-break puts it on row 2
-  }
-
-  .also-on-row-2 {
-    @include columns(3);    // all following elements affected as well
-  }
-}
-```
+With Lucid, this practice is no longer necessary - you can now adjust the width of grid elements individually. Just add your total borders / padding together and pass the negative value as a mixin parameter.
 
-###Using with Borders and Padding `+columns( $columns (int), $adjustment (px) )`
+Note: Adjusting the width of a grid element makes it less suitable as a parent element for nesting (it can no longer contain the full expected width).
 
-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:
+####Old Way:
 
 ```html
 <div class="container">
@@ -229,7 +182,7 @@ With other grids, styling an inner `<div>` is often the cleanest method to accom
 }
 ```
 
-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 the negative value as a mixin parameter. Like this:
+####With Lucid:
 
 ```html
 <div class="container">
@@ -248,14 +201,14 @@ With Lucid, this practice is no longer necessary, as you can adjust the width of
 }
 ```
 
-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 `+columns( $columns (int), $adjustment (px), $gutters (0 || none) )`
 
-###Gutterless Elements `+columns( $columns (int), $adjustment (px), $gutters (0 || none) )`
+Sometimes, it's convenient to have grid elements without gutter margins. This is especially useful for nesting elements or defining custom margins.
 
-Sometimes, it's convenient to have grid units without gutters. For example, when you want to nest elements within other elements:
+To turn off gutters, just pass a third parameter:
 
 ```scss
-.gutterless {
+.gutterless {                     // a gutterless element
   @include columns(9, 0, none);   // $gutters can accept 'none' or '0'
 
   .nested {
@@ -268,48 +221,104 @@ Sometimes, it's convenient to have grid units without gutters. For example, when
 }
 ```
 
+##Offset Positioning `+offset( $offset (int), $gutters (0 || none) )`
+
+Layouts oftentimes call for a bit of whitespace. Not a problem with Lucid. Just remember to specify whether the element you're including to has gutters or not - this is factored into the calculation.
+
+Unlike other grids that use padding or relative positioning to achieve this, Lucid does it with just `margin-left`. That means the element itself can still safely recieve background styling.
+
+```scss
+.offset-to-the-right {
+  @include columns(6);
+  @include offset(3);         // shifts element to the right 3 columns
+}
+
+.offset-to-the-left {
+  @include columns(6);
+  @include offset(-3);        // shifts element to the left 3 columns
+}
+
+.offset-gutterless {
+  @include columns(6, 0, none);
+  @include offset(3, none);   // include 'none' or '0' when grid element is gutterless
+}
+```
+
+##New Rows `+row-break`
+
+Elements that exceed the width of the container will automatically wrap into the next row. If you want to insert a "row break" manually, it's dead simple:
+
+```scss
+.container {
+  @include container;       // this 12 column container
+                            // would normally accomodate all 4 children
+  .on-row-1 {
+    @include columns(3);
+  }
+
+  .also-on-row-1 {
+    @include columns(3);
+  }
+
+  .on-row-2 {
+    @include columns(3);    // this would have been on row 1
+    @include row-break;     // +row-break puts it on row 2
+  }
+
+  .also-on-row-2 {
+    @include columns(3);    // all following elements affected as well
+  }
+}
+```
+
 #Advanced
 
-###Media Queries and Grid Reformatting `+grid-reinit`
+##Media Queries and Grid Reformatting `+grid-reinit`
+
+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.
 
-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:
+"Reinitialize" Lucid inside a media query (or any other a wrapping container) to adjust the size of grid elements within the container. Just preface it with a new `$grid-width` and/or `$grid-columns`.
 
 ```scss
+/* Full width grid */
+
 @include grid-init;
 
-// full width grid
 .container { @include container; }
 .sidebar { @include column(3); }
 .main { @include column(9); }
 
+/* Miniature grid within media query */
+
 @media screen and (max-width: 480px) {
 
   // redeclare one or more variables
   $grid-width: 480px;
+  $grid-columns: 6;
 
-  // 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); }
+  .sidebar { @include column(2); }
+  .main { @include column(4); }
 
 }
 ```
 
-###Modifying @extend Hooks
+##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):
+Lucid uses `@extend` internally to achieve leaner stylesheets. In order to do this, `+grid-init` outputs four benign selectors for `@extend` to "hook" onto. These selectors 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";
+
+@include grid-init;
 ```
 
-###Unsemantic Class Names `+grid-classes( $gutterless (bool), $prefix (str), $prefix-gutterless (str) )`
+##Unsemantic Class Names `+grid-classes( $gutterless (bool), $prefix (str), $prefix-gutterless (str) )`
 
 For testing purposes, or for those who are unwilling to part with old ways, Lucid provides a class name generator mixin:
 
@@ -326,3 +335,10 @@ For testing purposes, or for those who are unwilling to part with old ways, Luci
 @include grid-classes(true, 'grid-', 'gutterless-');
 ```
 
+#Your Turn
+
+Love it? Hate it? Bugs? Suggestions?
+
+[I'd love to know.](https://github.com/ezYZ/lucid/issues) Thanks for stopping by!
+
+\-Y

data/templates/project/_grid.scss

@@ -5,6 +5,7 @@
 // MIT License [https://github.com/ezYZ/lucid/blob/master/LICENSE.txt]
 //
 // @import this into your project or paste into your base/bootstrap file 
+// The variables included below are the defaults and are safe to remove.
 //
 //============================================================================//
 

data/templates/project/manifest.rb

@@ -9,9 +9,9 @@ help %Q{
 THE LUCID GRID
 plugin by Yifei Zhang [http://yifei.co]
 
-A smarter CSS grid for Compass.
+A Compass/SASS grid for developers who love semantics.
 
-For detailed documentation and examples, visit [https://github.com/ezYZ/lucid]
+A Compass/SASS grid that outputs lean, semantic stylesheets. Avoids CSS repetition on SASS compilation and reduces the need for wrapper <div>s.
 
 ***
 
@@ -24,7 +24,7 @@ welcome_message %Q{
 THE LUCID GRID
 plugin by Yifei Zhang [http://yifei.co]
 
-A smarter CSS grid for Compass.
+A Compass/SASS grid that outputs lean, semantic stylesheets. Avoids CSS repetition on SASS compilation and reduces the need for wrapper <div>s.
 
 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.5.0
+  version: 0.5.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-06-30 00:00:00.000000000Z
+date: 2011-07-01 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: compass
-  requirement: &78872390 !ruby/object:Gem::Requirement
+  requirement: &70127160 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: '0.11'
   type: :runtime
   prerelease: false
-  version_requirements: *78872390
+  version_requirements: *70127160
 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