carljm-compass-susy-plugin 0.2.0 → 0.3.0

data/README.mkdn

@@ -1,79 +1,153 @@
-Susy - Compass Plugin
+Susy - Compass Plugin 
 ================================
 
-Let me introduce you to Susy.
-
-Susy is a semantic CSS framework creator built native to [Compass](http://compass-style.org/).
-
-Susy is an expert at designing elastic (or fixed, if you swing that way) grids that will never activate that bloody side-scroll bar. Susy sets your width on the outer element (@grid-container@), adds a @max-width@ of @99%@ and builds the rest of your grid in percentages of the whole.
-
-Columns can also be nested by declaring the context along with the target width. Etc.
-
-Install
+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
+  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
+Create a Susy-based Compass Project 
 ==================================
 
-    compass -r susy -f susy <project name>
+  compass -r susy -f susy <project name>
 
-Then edit your `_base.sass`, `screen.sass` and `print.sass` files accordingly. A reset is added automatically.
+Then edit your `_base.sass`, `screen.sass` and `print.sass` files accordingly.
+A reset is added automatically.
 
-Customizing your Grid System
+Customizing your Grid System 
 ============================
 
-To create a grid system, set the `!grid_unit`, `!total_cols`, `!col_width`, and
-`!gutter_width` variables in your `base.sass` and then use the `+grid-container` mixin to declare
-your container element.
+Start in your `_base.sass` file. That's where you set all your defaults.
+
+To create a grid system, 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), and `!gutter_width` (width of gutters) variables in your
+`_base.sass`.
 
 Example:
 
-    !grid_unit = "em"
-    !total_cols = 10
-    !col_width = 7
-    !gutter_width = 1
+  !grid_unit = "em" 
+  !total_cols = 10 
+  !col_width = 7 
+  !gutter_width = 1
+  !side_gutter_width = 2
 
-    #page
-      +grid-container
+The default values are 16 columns, 4em column widths, and 1em gutters and side
+gutters that match the internal ones.
 
-The default values are 16 columns, column width of 4em and gutter width 1em.
+Of course, designing in `em`'s, you'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-container`.
 
-Making Semantic Grids
-=====================
+Example:
+
+  !base_font_size_px = 14 
+  !base_line_height_px = 16
 
-* Use the `+grid-container` mixin to declare your container element.
+The default values are 12px fonts with an 18px line-height.
 
-* Use the `+grid-col` mixin to declare a grid element. The first argument
-is the number of cols, the second is the size (in grid columns) of the
-containing element (defaults to the containers total_cols).
+`_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).
+
+Making Semantic Grids 
+=====================
 
-* Use the `+last` mixin to declare the last comumn in a row.
+* Use the `+susy` mixin to get things ready, set your base fonts 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 `+right` mixin to float a grid item to the right instead of left.
+* 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 `+grid-prefix` and `+grid-suffix` mixins to add grid columns
-before or after a grid element.
+* Use the `+column` mixin to declare a grid element. The first
+  argument is the number of columns to span, the second (optional)
+  argument is the size (in columns) of the containing element when
+  nesting (defaults to the container's `!total_cols`).
 
+* Use the `+alpha` and `+omega` mixins to declare the first and last
+  elements in a row, or inside a nested element. In the latter case,
+  each of these mixins takes one argument, which is the size (in
+  columns) of the containing element.
 
+* Use the `+prefix` and `+suffix` mixins with one argument to add that
+  many grid columns as margin before or after a grid element. These
+  mixins also take an optional second argument, the size in columns of
+  the containing element when nested.
 
 Example:
 
-    #page
-      +grid-container
-      #left-nav
-        +grid-col(3)
-      #main-content
-        +grid-prefix(2)
-        +grid-col(4, 10)
-        +last
-        +right
-
-Extra Utility Mixins
+  body 
+    +susy
+
+    #page 
+      +container 
+      #left-nav 
+        +columns(3) 
+        +alpha
+        #main-content 
+          +prefix(2)
+          +columns(4, 10) 
+          +omega 
+          .header 
+            +columns(1, 4) 
+          .article 
+            +columns(3, 4) 
+            +omega
+
+Extra Utility Mixins 
 =====================
 
-Extra utilities are included in Susy's `utils.sass` file, with additional list options, 
-experimental (CSS3/proprietary) CSS, and more.
+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.
+
+* `+inline-italic` because some fonts/browsers add line-height when you
+  explicitly set italics on an inline element - this takes some away.
+
+And then the fun stuff:
+
+* `+opacity(!opacity)` adds cross-browser opacity settings (takes a range of 0
+  - 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 and CSS3.

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

data/compass-susy-plugin.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{compass-susy-plugin}
-  s.version = "0.2.0"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Eric Meyer"]

data/lib/susy/sass_extensions.rb

@@ -2,25 +2,32 @@ require 'sass'
 
 module Sass::Script::Functions
   # set the Susy column and gutter widths and number of columns
-  #  column and gutter widths should be sent as unitless numbers, 
+  #  column, gutter and padding widths should be sent as unitless numbers, 
   #  though they may "really" be ems or pixels (_grid.sass handles units).
   # return total width of container (without units)
-  def container(total_columns, column_width, gutter_width)
+  def container(total_columns, column_width, gutter_width, side_gutter_width)
     @@susy_total_columns = total_columns.value
     @@susy_column_width = Float(column_width.value)
     @@susy_gutter_width = Float(gutter_width.value)
+    @@susy_side_gutter_width = Float(side_gutter_width.value)
     context
   end
 
-  # return the width of 'n' columns plus 'n - 1' gutters
+  # return the width of 'n' columns plus 'n - 1' gutters 
+  # plus page padding in non-nested contexts
   def context(n = nil)
     begin
       n = n.value
     rescue NoMethodError
+      n = false
+    end
+    sg = 0
+    if !n
       n = @@susy_total_columns
+      sg = @@susy_side_gutter_width
     end
     c, g = [@@susy_column_width, @@susy_gutter_width]
-    Sass::Script::Number.new((n * c) + ((n - 1) * g))
+    Sass::Script::Number.new(((n * c) + ((n - 1) * g)) + (sg * 2))
   end
 
   # return the percentage width of 'number' columns in a context of
@@ -40,6 +47,14 @@ module Sass::Script::Functions
     Sass::Script::Number.new((g / context_width) * 100)
   end
 
+  # return the percentage width of a single side gutter in a context of
+  #  'context_columns'
+  def side_gutter(context_columns = nil)
+    context_width = context(context_columns).value
+    sg = @@susy_side_gutter_width
+    Sass::Script::Number.new((sg / context_width) * 100)
+  end
+
   # return the percentage width of a single column in a context of
   #  'context_columns'
   def column(context_columns = nil)

data/sass/susy/_grid.sass

@@ -1,31 +1,69 @@
+//** Grid Settings **//
+
+//**
+  Your basic units for the grid
 !grid_unit ||= "em"
 !total_cols ||= 16
 !col_width ||= 4
 !gutter_width ||= 1
-!container_width = container(!total_cols, !col_width, !gutter_width)
+!side_gutter_width ||= !gutter_width
+!container_width = container(!total_cols, !col_width, !gutter_width, !side_gutter_width)
+
 
-=grid-container
+//** 
+  set on the outer grid containing element.
+=container(!align = "left")
+  //  clear all floated columns
   +clearfix
-  :margin-left auto
-  :margin-right auto
+  //  align the text back to the left (override for other alignments)
+  :text-align= !align
+  //  use auto horizontal margins to center your page in the body
+  :margin
+    :left auto
+    :right auto
+  //  set the page width based on column settings
   :width= !container_width + !grid_unit
-  :max-width 99%
+  //  never exceed 100% of the browser window (no side-scrolling)
+  :max-width 100%
 
-=grid-col(!n, !context = !total_cols)
+
+//** 
+  set on any column element, even nested ones.
+  the first agument [required] is the number of columns to span
+  the second argument is the context (columns spanned by parent)
+  this is required in any nested context
+  by default a grid-col is floated left with a right gutter
+  override that with +float("right"), +first or +last
+=columns(!n, !context = false)
+  //  the width of the column is set as a percentage of the context
   :width= columns(!n, !context) + "%"
-  :display inline
-  :float left
+  //  the column is floated left
+  +float("left")
+  //  the right gutter is added as a percentage of the context
   :margin-right= gutter(!context) + "%"
 
-=last
-  :margin-right= 0
-
-=right
-  :display inline
-  :float right
-
-=grid-prefix(!n, !context = !total_cols)
+//** 
+  set on any column to add empty colums before or after
+=prefix(!n, !context = false)
   :padding-left= columns(!n, !context) + gutter(!context) + "%"
 
-=grid-suffix(!n, !context = !total_cols)
+=suffix(!n, !context = false)
   :padding-right= columns(!n, !context) + gutter(!context) + "%"
+
+//**  
+  set on the first column of a row to take side-gutters into account
+  - must override `!nested` for nested columns
+=alpha(!nested = false)
+  @if !nested
+    :margin-left 0
+  @else
+    :margin-left= side_gutter() + "%"
+
+//**  
+  set on the last column of a row to take side-gutters into account
+  - must override `!nested` for nested columns
+=omega(!nested = false)
+  @if !nested
+    :margin-right 0
+  @else
+    :margin-right= side_gutter() + "%"

data/sass/susy/_utils.sass

@@ -1,6 +1,8 @@
 @import compass/utilities.sass
 
-// removes all background images and colors from the element and offspring, and adds a grid image
+//** 
+  removes all background images and colors from the element and offspring
+  then adds a grid image of your choosing
 =show-grid(!src)
   :background
     :image= "url("!src")"
@@ -9,26 +11,28 @@
   *
     :background transparent
 
-// an inline-block list that works in IE
+//** 
+  an inline-block list that works in IE
+  for those awkward moments when a floated horizontal list just wont cut it
 =inline-block-list(!hpad = 0)
   +horizontal-list-container
   li
     +no-bullet
+    :white-space no-wrap
     +inline-block
     :padding 
       :left= !hpad
       :right= !hpad
-    &.first, &:first-child
-      :padding-left 0px
-    &.last, &:last-child
-      :padding-right 0px
 
-// hide an element from the viewport, but keep it for accessability
+//** 
+  hide an element from the viewport, but keep it around for accessability
 =hide
   :position absolute
   :top -9999em
 
-// a skip-to-content accessibility link that will appear on focus
+//** 
+  a skip-to-content accessibility link that will appear on focus
+  set the location arguments if you care where it appears
 =skip-link(!t = 0, !r = false, !b = false, !l = false)
   +hide
   :display block
@@ -43,69 +47,75 @@
       :left= !l
     :z-index 999
 
-// Because some serif fonts add line-height when switching to italics inline:
-=inline-italic
-  :font-style italic
-  :line-height .5
+// EXPERIMENTAL
 
+//**
+  transparency for everyone!
+=opacity(!o = 1)
+  :filter= "alpha(opacity=" + (!o*100) + ")"
+  :-moz-opacity= !o
+  :-khtml-opacity= !o
+  :opacity= !o
 
-// EXPERIMENTAL
+//**
+  rounded corners for Mozilla, Webkit and the future
+=border-radius(!r)
+  /* Mozilla (FireFox)
+  -moz-border-radius = !r
+  /* Webkit (Safari, Chrome)
+  -webkit-border-radius = !r
+  /* CSS3
+  border-radius = !r
 
-=trans(!o = 100)
-  :filter= "alpha(opacity=" + !o + ")"
-  :-moz-opacity= !o / 100
-  :-khtml-opacity= !o / 100
-  :opacity= !o / 100
+=border-top-left-radius(!tl)
+  /* Mozilla (FireFox)
+  -moz-border-radius-topleft= !tl
+  /* Webkit (Safari, Chrome)
+  -webkit-border-top-left-radius= !tl
+  /* CSS3
+  border-top-left-radius= !tl
 
-=rounded(!trbl = false, !tl = false, !tr = false, !br = false, !bl = false)
-  @if !trbl
-    /* Mozilla (FireFox)
-    -moz-border-radius= !trbl
-    /* Webkit (Safari, Chrome)
-    -webkit-border-radius= !trbl
-    /* CSS3
-    border-radius= !trbl
-  @if !tl
-    /* Mozilla (FireFox)
-    -moz-border-radius-topleft= !tl
-    /* Webkit (Safari, Chrome)
-    -webkit-border-top-left-radius= !tl
-    /* CSS3
-    border-top-left-radius= !tl
-  @if !tr
-    /* Mozilla (FireFox)
-    -moz-border-radius-topright= !tr
-    /* Webkit (Safari, Chrome)
-    -webkit-border-top-right-radius= !tr
-    /* CSS3
-    border-top-right-radius= !tr
-  @if !br
-    /* Mozilla (FireFox)
-    -moz-border-radius-bottomright= !br
-    /* Webkit (Safari, Chrome)
-    -webkit-border-bottom-right-radius= !br
-    /* CSS3
-    border-bottom-right-radius= !br
-  @if !bl
-    /* Mozilla (FireFox)
-    -moz-border-radius-bottomleft= !bl
-    /* Webkit (Safari, Chrome)
-    -webkit-border-bottom-left-radius= !bl
-    /* CSS3
-    border-bottom-left-radius= !bl
+=border-top-right-radius(!tr)
+  /* Mozilla (FireFox)
+  -moz-border-radius-topright= !tr
+  /* Webkit (Safari, Chrome)
+  -webkit-border-top-right-radius= !tr
+  /* CSS3
+  border-top-right-radius= !tr
+
+=border-bottom-right-radius(!br)
+  /* Mozilla (FireFox)
+  -moz-border-radius-bottomright= !br
+  /* Webkit (Safari, Chrome)
+  -webkit-border-bottom-right-radius= !br  
+  /* CSS3
+  border-bottom-right-radius= !br
+
+=border-bottom-left-radius(!bl)
+  /* Mozilla (FireFox)
+  -moz-border-radius-bottomleft= !bl
+  /* Webkit (Safari, Chrome)
+  -webkit-border-bottom-left-radius= !bl
+  /* CSS3
+  border-bottom-left-radius= !bl
 
-=box_model(!bm)
+//**
+  change the box model for Mozilla, Webkit, IE8 and the future
+=box-sizing(!bs)
   /* Mozilla (FireFox)
-  -moz-box-sizing= !bm
+  -moz-box-sizing= !bs
   /* Webkit (Safari, Chrome)
-  -webkit-box-sizing= !bm
+  -webkit-box-sizing= !bs
   /* IE (8)
-  -ms-box-sizing= !bm
+  -ms-box-sizing= !bs
   /* CSS3
-  box-sizing= !bm
+  box-sizing= !bs
 
-=box_shadow(!ho, !vo, !b, !c )
+//**
+  box shadow for Webkit and the future
+  - arguments are horizontal offset, vertical offset, blur and color
+=box-shadow(!ho, !vo, !b, !c )
   /* Webkit (Safari, Chrome)
   -webkit-box-shadow= !ho !vo !b !c
   /* CSS3
-  box-shadow= !ho !vo !b !c
+  box-shadow= !ho !vo !b !c

data/templates/project/_base.sass

@@ -1,41 +1,44 @@
-// 
-//  Susy: My own damn Compass/SASS framework
-//  by Eric Meyer
-//
+//**
+//  Susy: Elastic-Fluid grids without all the math
+//  by Eric Meyer and OddBird Collective
+//  oddbird. 
+//**
 
 
 /* RESET STYLES
 @import compass/reset.sass
 
-// GRID
-// override these values as needed for your grid layout
 
+//** 
+  GRID
+  un-comment and override these values as needed for your grid layout 
+  (defaults are shown)
 // !grid_unit = "em"
-// !total_cols = 10
-// !col_width = 7
+// !total_cols = 16
+// !col_width = 4
 // !gutter_width = 1
+// !side_gutter_width = !gutter_width
 
-// MIXINS
-//  (don't move these @imports above the GRID overrides)
-@import susy/utils.sass
-@import susy/grid.sass
+//** 
+  FONT-SIZE
+  un-comment and override these values as needed (defaults are shown)
+  - you set the font and line heights in pixels.
+  - Susy will do the math and give you !base_font_size and !base_line_height 
+    variables, set flexibly against the common browser default of 16px
+// !base_font_size_px = 12
+// !base_line_height_px = 18
+
+// SUSY
+//  (don't move this @import above the GRID and FONT-SIZE overrides)
+@import susy/susy.sass
 
 
 // COLORS
+// set any colors you will need later
 !dark = #000
 !light = #fff
 
-
-// FONT PRESETS
-
-// You set the font and line heights in pixels
-!base_font_size_px ||= 12
-!base_line_height_px ||= 18
-
-// SUSY can do the math to make that relative
-!base_line_height = (!base_line_height_px / !base_font_size_px) + "em"
-!base_font_size = (!base_font_size_px / 16) + "em"
-
+// FONTS
 // Give yourself some font stacks to work with
 =sans-family
   :font-family 'Futura Medium', 'Century Gothic', AppleGothic, sans-serif
@@ -70,19 +73,20 @@ input[type=submit]
 /* block tags
 p
 
-=list_default(!ol = false)
+=list-default(!ol = false)
   @if !ol
-    :list-style decimal-leading-zero
-    :margin 0 1.5em 1.5em 2em
+    :list-style decimal
+    :margin 0 1.5em 1.5em 1.5em
   @else
     :list-style disc
-    :margin 0 1.5em 1.5em 1.5em 
+    :margin 0 1.5em 1.5em 1.5em
+
 
 ol
-  +list_default("ol")
+  +list-default("ol")
 
 ul
-  +list_default
+  +list-default
 
 blockquote
 

data/templates/project/ie.sass

@@ -5,11 +5,4 @@
     <link href="/stylesheets/ie.css" media="screen, projection" rel="stylesheet" type="text/css" />
   <![endif]-->
 
-/*
-  Theme Name: DEFAULT
-  Theme URI: http://eric.dirtcircle.com/
-  Description: A default style using the SUSY plugin for Compass/SASS
-  Version: 1
-  Author: Eric Meyer
-
 @import base.sass

data/templates/project/print.sass

@@ -2,13 +2,5 @@
   Welcome to Susy. Use this file to define print styles.
   Import this file using the following HTML or equivalent:
   <link href="/stylesheets/print.css" media="print" rel="stylesheet" type="text/css" />
-
-/*
-  Theme Name: DEFAULT
-  Theme URI: http://eric.dirtcircle.com/
-  Description: A default style using the SUSY plugin for Compass/SASS
-  Version: 1
-  Author: Eric Meyer
-
   
 @import base.sass

data/templates/project/screen.sass

@@ -3,13 +3,6 @@
   Import this file using the following HTML or equivalent:
   <link href="/stylesheets/screen.css" media="screen" rel="stylesheet" type="text/css" />
 
-/*
-  Theme Name: DEFAULT
-  Theme URI: http://eric.dirtcircle.com/
-  Description: A default style using the SUSY plugin for Compass/SASS
-  Version: 1
-  Author: Eric Meyer
-
 @import base.sass
 
 /* STRUCTURE
@@ -25,5 +18,8 @@
 
 
 /* DEBUG
-/ #page
-/   +show-grid("../images/grid.gif")
+  uncomment, adjust and use for debugging
+  
+/** 
+  #page
+    +show-grid("../images/grid.gif")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: carljm-compass-susy-plugin
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Eric Meyer