README.mkdn in carljm-compass-susy-plugin-0.2.0 vs README.mkdn in carljm-compass-susy-plugin-0.3.0

- old
+ new

@@ -1,79 +1,153 @@ -Susy - Compass Plugin +Susy - Compass Plugin ================================ -Let me introduce you to Susy. +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. -Susy is a semantic CSS framework creator built native to [Compass](http://compass-style.org/). +Using simple mixins, columns can be created, suffixed, prefixed, and nested +easily - and always in flexible percentages. -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 +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: -* Use the `+grid-container` mixin to declare your container element. + !base_font_size_px = 14 + !base_line_height_px = 16 -* 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). +The default values are 12px fonts with an 18px line-height. -* Use the `+last` mixin to declare the last comumn in a row. +`_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). -* Use the `+right` mixin to float a grid item to the right instead of left. +Making Semantic Grids +===================== -* Use the `+grid-prefix` and `+grid-suffix` mixins to add grid columns -before or after a grid element. +* 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 `+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 `+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 + body + +susy -Extra Utility Mixins + #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. \ No newline at end of file +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.