compass-susy-plugin 0.6.2

data/LICENSE.txt

@@ -0,0 +1,28 @@
+Copyright (c) 2009, Eric Meyer
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of the author nor the names of other
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Manifest

@@ -0,0 +1,17 @@
+lib/susy/compass_plugin.rb
+lib/susy/sass_extensions.rb
+lib/susy.rb
+Manifest
+Rakefile
+README.mkdn
+sass/susy/_grid.sass
+sass/susy/_utils.sass
+sass/susy/_text.sass
+sass/susy/_susy.sass
+templates/project/print.sass
+templates/project/screen.sass
+templates/project/ie.sass
+templates/project/_base.sass
+templates/project/manifest.rb
+VERSION
+LICENSE.txt

data/README.mkdn

@@ -0,0 +1,233 @@
+Susy - Compass Plugin 
+=====================
+
+Susy is a semantic CSS framework creator entirely native to
+[Compass](http://compass-style.org/).
+Susy is an expert at fluid grids in an elastic (or fluid, or fixed) shell that
+will never activate that bloody side-scroll bar. Susy sets your width on the
+outer element (`container`), adds a `max-width` of `100%` and builds the rest
+of your grid in percentages. The philosophy and technique are based on
+[Natalie Downe](http://natbat.net/)'s "[CSS
+Systems](http://natbat.net/2008/Sep/28/css-systems/)" - which introduces
+difficult math in the service of beautiful structure. With the power of
+Compass/Sass, Susy will do that math for you.
+
+Using simple mixins, columns can be created, suffixed, prefixed, and nested
+easily - and always in flexible percentages.
+
+Install 
+=======
+
+    sudo gem sources --add http://gems.github.com/ 
+    sudo gem install chriseppstein-compass 
+    sudo gem install ericam-compass-susy-plugin
+
+Create a Susy-based Compass Project 
+===================================
+
+    compass -r susy -f susy <project name>
+
+Then edit your `_base.sass`, `screen.sass` and `print.sass` files accordingly.
+A reset is added automatically.
+
+Philosophy and Goals
+--------------------
+
+The method comes from [Natalie Downe](http://natbat.net/)'s "[CSS
+Systems](http://natbat.net/2008/Sep/28/css-systems/)", but I'll cover it here.
+
+It is important for accessibility and usability that we are:
+
+* Responsive to text sizing: In order for our site to be accessible we need to
+  allow different font-sizes to be set by the client. In order to maintain
+  design integrity of proportions and line-lengths, the grid needs to respond
+  to those sizes.
+
+* Responsive to window sizing: In order to maintain usability across
+  platforms/monitors, our grid needs to respond to the size of the viewport.
+  This is mainly an issue as the viewport shrinks and we are given a
+  side-scroll bar. No one likes that. On the large end our design integrity
+  and line lengths are more important than taking up all the possible space.
+
+In order to achieve both we need to combine the best of the elastic (em-based)
+and fluid (%-based) models. The solution is simple: First we build a fluid
+grid, then place it inside an elastic shell, and apply a maximum width to that
+shell so that it never exceeds the size of the viewport. It's simple in
+theory, but daunting in practice, as you constantly have to adjust your math
+based on the context.
+
+But Susy harnesses the power of Compass and Sass to do all the math for you.
+
+Grid Basics
+===========
+
+* Set up your default grid values (total columns, column width, gutter
+  width, side gutter width), your base font size, and other style defaults
+  in `_base.sass`.
+
+* Create your grid in `screen.sass`: apply the `+susy` mixin to the `body`
+  element and the `+container` mixin to the element that contains the page
+  grid.
+
+* Use the `+columns` mixin to declare the width in columns of an element,
+  or `+full` for any element spanning the full width of its context.
+
+* Use `+alpha` and `+omega` to declare elements which include the first or
+  last column within their parent element (`+full` to declare both `+alpha`
+  and `+omega`). Note: `+alpha` is actually only needed in the very top level,
+  and does nothing in nested contexts. Neither is needed on a `+full` element.
+
+* Use `+prefix` or `+suffix` to give the width (in columns) of an elements
+  left or right margin, or `+pad` to give both `+prefix` and `+suffix` at
+  once.
+
+* In nested contexts, all of these mixins take an extra final argument, the
+  width in columns of the parent (nesting) element.
+
+That's it for the basics! Here's a sample Susy grid layout:
+
+    body
+      +susy
+     
+    #page
+      +container
+     
+    #brand
+      +full
+      +pad(1,1)
+      h1
+        +full(8)
+        +pad(1,2,8)
+        
+    #nav
+      +columns(2)
+      +alpha
+     
+    #content
+      +columns(8)
+      +omega
+      #description
+        +columns(5,8)
+      #credit
+        +columns(3,8)
+        +omega(8)
+
+Tutorial
+========
+
+For more details, read [the tutorial](http://www.oddbird.net/susy/tutorial/).  
+It's also included with Susy in the docs/ folder.
+
+Extra Utility Mixins 
+=====================
+
+Extra utilities are included in Susy's `utils.sass` file, with additional list
+options, experimental (CSS3/proprietary) CSS, and more.
+
+* `+show-grid(!src)` will remove all your backgrounds and repeat the specified
+  grid image on an element. Good for testing your baseline grid.
+
+* `+inline-block-list([!horizontalpadding])` for making lists inline-block
+  when floating just won't do the trick.
+
+* `+hide` for hiding content from visual browsers while keeping accessability
+  intact.
+
+* `+skip-link([!top = 0, !right, !bottom, !left])` hide a link, and then show
+  it again on focus. the TRBL settings allow you to place it absolutely on
+  display. Default will be top left of the positioning context.
+
+And then the fun stuff:
+
+* `+opacity(!opacity)` adds cross-browser opacity settings (takes a range of
+  0 to 1).
+
+* `+border-radius(!radius)` (`+border-bottom-left-radius` etc. all work) for
+  rounded corners in supporting browsers.
+
+* `+box-sizing(!model)` for setting the box sizing model in supporting
+  browsers.
+
+* `+box-shadow(!verticaloffset, !horizontaloffset, !blur, !color)` for
+  box-shadow in webkit, mozilla and CSS3.
+
+* `+column-count(!number)`, `+column-gap(!length)`, `+column-width(!length)`,
+  and `+column-rule(!width, !style, !color)` for CSS columns in webkit,
+  mozilla and CSS3.
+
+Advanced Options
+================
+
+Susy is built for flexibility, so that you always write the code you want to
+write. While everything should 'just work' out of the box, there are plenty of
+advanced options hidden inside. Here's a few:
+
+* `!hacks` is a boolean constant that you can set in your base.sass file to
+  choose between using targeted hacks for IE (a variation of the star hack in
+  most cases) in your screen.css, or using a conditional-comment targeted
+  ie.css. All the needed mixins are available for either setting. `!hacks` is
+  true by default so there is no extra work maintaining multiple files unless
+  you want to.
+
+    Example 1:
+    
+        !hacks = true
+    
+        #nav
+          +inline-block-list
+    
+    Example 2:
+    
+        !hacks = false
+      
+        (in screen.sass)
+        #nav
+          +inline-block-list
+        
+        (in ie.sass)
+        #nav li
+          +ie-inline-block
+
+    It requires more maintenance on your part, but the result is a
+    hack-free output.
+    
+    The susy mixins that use either hacks or targeted mixins are
+    `+omega` (`+ie-omega([!right-floated = false])`), `+inline-block`
+    (`+ie-inline-block`), and `+inline-block-list` which sets
+    `+inline-block` on the list items.
+    
+    The ie-specific mixins only add the needed ie-specific adjustments,
+    so they need to be used in addition to their counterparts, not on
+    their own.
+
+* `gutter(!context)` is a function that you can call at any time to return the
+  size of a gutter in your given context using percentages. The number is
+  returned without units so that you can perform math on it. In order to use
+  it, you will have to add "%" to it.
+
+    Example:
+        
+        #nav
+          :padding-right= gutter(5) + "%"
+
+* `columns(!number, !context)` returns the span of `!number` columns in
+  `!context` as a percentage (again without the units declared). This span
+  includes any gutters between the columns spanned.
+
+    Example:
+        
+        #nav
+          :padding-left= columns(3,5) + "%"
+
+* `side_gutter()` is also available and takes no arguments since it is always
+  used at the top nesting level.
+
+* `px2em()` takes one numeric argument representing the number of pixels you
+  want to mimic. The return is an em value (with no units declared) that
+  approximates that number of pixels. Useful for keeping your entire design
+  fluid.
+  
+    Example:
+    
+        #nav
+          :border-bottom= px2em(2) + "em"

data/Rakefile

@@ -0,0 +1,22 @@
+require 'fileutils'
+require 'sass'
+require 'lib/susy/sass_extensions'
+
+begin
+  require 'echoe'
+ 
+  Echoe.new('compass-susy-plugin', open('VERSION').read) do |p|
+    # p.rubyforge_name = 'susy'
+    p.summary = "A Compass grid system plugin."
+    p.description = "Susy is a ground-up native Compass plugin grid system that takes full advantage of Sass' capabilities to remove the tedium from grid-based web design."
+    p.url = "http://github.com/ericam/compass-susy-plugin"
+    p.author = ['Eric Meyer']
+    p.email = "eric@oddbird.net"
+    p.dependencies = ["chriseppstein-compass"]
+    p.has_rdoc = false
+  end
+ 
+rescue LoadError => boom
+  puts "You are missing a dependency required for meta-operations on this gem."
+  puts "#{boom.to_s.capitalize}."
+end

data/VERSION

@@ -0,0 +1 @@
+0.6.2

data/compass-susy-plugin.gemspec

@@ -0,0 +1,36 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{compass-susy-plugin}
+  s.version = "0.6.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Eric Meyer"]
+  s.date = %q{2009-07-12}
+  s.description = %q{Susy is a ground-up native Compass plugin grid system that takes full advantage of Sass' capabilities to remove the tedium from grid-based web design.}
+  s.email = %q{eric@oddbird.net}
+  s.extra_rdoc_files = ["lib/susy/compass_plugin.rb", "lib/susy/sass_extensions.rb", "lib/susy.rb", "README.mkdn"]
+  s.files = ["lib/susy/compass_plugin.rb", "lib/susy/sass_extensions.rb", "lib/susy.rb", "Manifest", "Rakefile", "README.mkdn", "sass/susy/_grid.sass", "sass/susy/_utils.sass", "sass/susy/_text.sass", "sass/susy/_susy.sass", "templates/project/_base.sass", "templates/project/screen.sass", "templates/project/print.sass", "templates/project/ie.sass", "templates/project/manifest.rb", "VERSION", "LICENSE.txt", "docs/tutorial/index.mkdn", "docs/tutorial/figures/susy_element.png", "docs/tutorial/figures/susy_grid.png", "compass-susy-plugin.gemspec"]
+  s.homepage = %q{http://github.com/ericam/compass-susy-plugin}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Compass-Susy-plugin", "--main", "README.mkdn"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{compass-susy-plugin}
+  s.rubygems_version = %q{1.3.3}
+  s.summary = %q{A Compass grid system plugin.}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<chriseppstein-compass>, [">= 0"])
+      s.add_development_dependency(%q<echoe>, [">= 0"])
+    else
+      s.add_dependency(%q<chriseppstein-compass>, [">= 0"])
+      s.add_dependency(%q<echoe>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<chriseppstein-compass>, [">= 0"])
+    s.add_dependency(%q<echoe>, [">= 0"])
+  end
+end

data/docs/tutorial/index.mkdn

@@ -0,0 +1,303 @@
+Susy Tutorial
+=============
+
+Once you've [installed
+everything](http://github.com/ericam/compass-susy-plugin/tree/master) we can
+start building our grid. I'll walk you through the steps. I'm starting with
+the assumption that you already know CSS and the Compass/Sass syntax. If you
+don't, check out [Chris Eppstein's great
+intro](http://wiki.github.com/chriseppstein/compass).
+
+For a brief overview of Susy's philosophy and goals, see [the
+README](http://github.com/ericam/compass-susy-plugin/tree/master#readme).
+
+On Susy's Terms
+---------------
+
+Here are the terms to understand for following along and using Susy:
+
+* There is always a **container** element that wraps the page. This container
+  will act as our elastic shell. The **container** also represents a grid
+  structure made up of **columns**, **gutters** between the columns, and
+  **side gutters** on the outside edges of the grid.
+
+  [![The Susy Grid](figures/susy_grid.png)](figures/susy_grid.png)
+
+* The base **context** is the number of columns in your grid system, and any
+  direct children of the **container** will use that base as their
+  **context**.  However, as you continue to nest elements within each other
+  that context will change. Just remember that the **context** is always the
+  number of columns spanned by the parent element.
+
+* There are any number of **grid elements** making up the structure of our
+  site, nested within the **container**. Each grid element has a width that
+  spans any number of **columns** along with the **gutters** between those
+  columns (number of columns minus one), and a right-margin that represents
+  the gutter to the right of it.
+
+  [![The Susy Grid Element](figures/susy_element.png)](figures/susy_element.png)
+
+* A **grid element** might also include a **prefix** and/or **suffix** added
+  as padding on either side. Any **prefix** or **suffix** will span the number
+  of **columns** given as argument, as well as all associated **gutters** (in
+  this case the same number of gutters as columns).
+
+* Any **grid elements** that span the first or last columns in any given
+  context will sometimes need to handle gutters in special ways. These will be
+  referred to as the **alpha** and **omega** elements. One element that spans
+  an entire context (a header or footer perhaps) may be both **alpha** and
+  **omega**.
+
+Customizing your Grid System 
+----------------------------
+
+So let's get started. We're going to build a website for Susy. [This
+website](http://www.oddbird.net/susy/). It's a simple site but it covers
+everything you need to get started on your own.
+
+Create yourself a Compass project using Susy:
+
+    compass -r susy -f susy susy_tutorial
+
+Inside the susy_tutorial directory, create an `index.html` file. You can [grab
+my source](01_target/index.html).
+
+Start in your `_base.sass` file (in the `src` directory). That's where you set
+all your defaults.
+
+To create a grid, set the `!grid_unit` (units that your grid is based in),
+`!total_cols` (total number of columns in your grid), `!col_width` (width of
+columns), `!gutter_width` (width of gutters), and `!side_gutter_width` (width
+of side gutters) variables.
+
+The default values are 16 columns, 4em column widths, 1em gutters and side
+gutters that match the internal ones. But we want a 10 column grid, with 5em
+columns, 2em gutters and 1em side-gutters.
+
+Take a look at our target site again, this time [with a grid
+overlay](01_target/).
+
+So we'll set our grid like this:
+
+    !grid_unit = "em" 
+    !total_cols = 10 
+    !col_width = 5 
+    !gutter_width = 2
+    !side_gutter_width = 1
+
+Of course, designing in em's, we'll want to get your font sizes set to make
+this all meaningful. Do that by assigning a pixel value (without the units) to
+`!base_font_size_px` and `!base_line_height_px`. Susy will convert those to a
+percentage of the common browser default (16px) and apply them to your grid.
+
+The default values here are 12px fonts with an 18px line-height. For us:
+
+    !base_font_size_px = 14 
+    !base_line_height_px = 21
+
+`_base.sass` also has everything you need for setting default font families,
+colors to reuse throughout, and default styles for all those elements that
+ought have a default (but don't because of the reset). we're going to skip
+that for now and play with the fun toys. You can look around at the other
+defaults and set what you like, or juse use [mine](../src/_base.sass).
+
+
+Making Semantic Grids 
+---------------------
+
+First the explanation:
+
+* Use the `+susy` mixin to get things ready, set your base font sizes and
+  center your grid in the browser window. Change the alignment of your grid in
+  the window with an optional `left | center | right` argument.
+
+* Use the `+container` mixin to declare your container element. Besides
+  building the grid shell, this sets your horizontal margins to auto (for
+  centered designs) and returns your text-alignment to "left". Change the
+  internal text alignment with an optional `left | center | right` argument.
+
+* Use the `+columns` mixin to set the width (in columns) of a grid element.
+  The first argument is the number of columns to span, the second (optional)
+  argument is the width (in columns) of the containing element when nesting.
+  If the element is not nested (its parent is the grid container), don't pass
+  a second argument. For an element that will span the full width (including
+  prefix and suffix), you can simply use `+full`, which takes one argument
+  of the context (in columns) when nested.
+
+* Use the `+alpha` and `+omega` mixins to declare the first and last elements
+  in a row. In a nested context `+omega` takes one argument repesenting its
+  context. `+alpha` is only needed in the very top level, and does nothing in
+  nested contexts. Neither one is needed on a `+full` element.
+
+* Use the `+prefix` and `+suffix` mixins with one argument to add that many
+  grid columns as padding before or after a grid element. These mixins also
+  take an optional second argument, the size in columns of the containing
+  element when nested.
+
+Then we do it. In `screen.sass`, we'll start by declaring our intent to use
+Susy, and our container:
+
+    body
+      +susy
+    
+    #page
+      +container
+
+That wasn't hard. You might ask why I didn't nest `#page` inside of `body`, as
+is so tempting and easy with Sass. It's part personal preference and part
+Natalie Downe's voice in my head. Don't nest when you don't need to. It keeps
+your output code much cleaner.
+
+While we're at it, why don't we get the fonts going right from the start?
+
+    #page
+      +container
+      +sans-family
+
+Perfect. Take a look at [the results](02_container/). So far we have:
+
+* Reset everything. This happens by default in the background.
+
+* Created an elastic container for our grid at 70em that goes fluid for small
+  windows (try it!).
+
+
+Laying Out The Components
+--------------------------
+
+It's time to lay out our grid components. We'll just work our way through the
+HTML, starting with our brand header (#brand). We can refer back to our [target
+site with a grid overlay](01_target/) to see what we need. Looks like our
+branding gets an entire row to itself, with the content starting one row
+in. For the sake of argument, let's say we want the header content contained
+within the middle 8 columns - one in from each end. That means it will be an 8
+column element, with 1 column prefixed and one suffixed, for a total of 10
+columns - the full width.
+
+    #brand
+      +columns(8)
+      +prefix(1)
+      +suffix(1)
+
+Since it spans both the first and last columns in the context we'll need to
+add:
+
+    +alpha
+    +omega
+
+Or we would have to, but there are several shortcuts available to us. To
+declare something as full width (both alpha and omega) we can just declare it
+as full:
+
+    +full
+
+There is also a shorcut for prefix and suffix additions (+pad), so we can
+simplify down to:
+
+    #brand
+      +full
+      +pad(1,1)
+
+Since we don't have an image in there yet, let's move the text over to line up
+with the future placement of our main content area. By turning the `h1` link
+into a grid element and prefixing a padding of one column, we can move the
+text without any effect on the image that will replace it (using the Compass
+utility `+replace-text`, though I'll leave the implementation of that as an
+exercise for you to figure out). To line it all up with the content below it,
+we'll assign it 5 columns in a context of 8, with the extra 3 split between a
+prefix of 1 and a suffix of 2 - giving it a full span again. This time we are
+nested and need to supply the context.
+
+    h1 a
+      +full(8)
+      +pad(1,2,8)
+
+Note: when not nested, you *must not declare a context*.  If you
+do, your side-gutters will be ignored. At every nested layer below that, even
+if the context hasn't changed, you *must declare a context* or it will try to
+add side-gutters again. That means even if you have one nested element
+wrapping the rest at full width and not changing the context, that wrapper
+does not get a context but its descendants do, even where that context is the
+same as the full page.
+
+For example, these *will not work*:
+    
+    /*because context is declared at the top level:*/
+    #page
+      +container
+      
+      .inner
+        +columns(8,10)
+    
+    /*because context is not declared in a nested level:*/
+    #page
+      +container
+      
+      .inner
+        +columns(10)
+        #brand
+          +columns(10)
+
+This *will work*:
+
+    #page
+      +container
+      
+      .inner
+        +columns(10)
+        #brand
+          +columns(8,10)
+
+We're only worried about structure for now, so the header is done. Let's move
+on to the navigation (#nav). The nav spans 2 columns, including the first
+column in it's context.
+
+    #nav
+      +columns(2)
+      +alpha
+
+Done. The #content (which includes both #description and #credit)
+spans the remaining 8 columns, including the last one.
+
+    #content
+      +columns(8)
+      +omega
+
+Done. #description spans 5; #credit spans 3 including the last. Both are in a
+nested context of 8, which we now need to pass on:
+
+    #description
+      +columns(5,8)
+    
+    #credit
+      +columns(3,8)
+      +omega(8)
+
+Done and done. All we have left is the footer (#site-info) spanning the full
+width, but with two blank columns on the left:
+
+    #site-info
+      +full
+      +prefix(2)
+
+Nested in the footer are `.license` and `.styles`, so let's put them in place.
+I'm going to say that each should match the width of the element visually
+above it on the page. So .license will span 5 columns in its context of 8, and
+.styles will span 3 including the last.
+
+    p.license
+      +columns(5,8)
+    p.styles
+      +columns(3,8)
+      +omega(8)
+
+And we're done. That's it. That's what Susy does. The details of making it
+pretty are left as an exercise for the reader, and have more to do with
+Compass than Susy.
+
+* [The resulting files](03_structure/src/) with [the site structure all in
+  place](03_structure/) (this should match what you have if you followed
+  along).
+
+* [My final styles](../src/) for [the site](http://www.oddbird.net/susy/).
+