Browse files

update changelog and readme to match unreleased version

  • Loading branch information...
1 parent 6102106 commit be8015737cb68ac70f4935a8479747a6961afa30 Eric Meyer committed May 4, 2012
Showing with 102 additions and 239 deletions.
  1. +33 −0 CHANGELOG.mkdn
  2. +69 −239 README.mkdn
View
33 CHANGELOG.mkdn
@@ -1,6 +1,39 @@
Susy Changelog
==============
+v1.0 [UNRELEASED]
+-----------------
+
+*Requires the latest unreleased master branch of Compass.*
+
+This release is loaded with new features, but don't let that fool you. Susy
+just became shockingly simple to use. See the README for updated usage details.
+
+New Features:
+
+* `omega` can now be set directly through the `columns` mixin - for much
+ more compact output.
+* Create responsive grid break-points using the `layout` and `at-breakpoint`.
+* `container` mixin now accepts one or more grids/breakpoints as a shortcut.
+* All mixins respect your `$legacy-support-for-ie` settings.
+* The `space` function can be used anywhere you need column+gutter math.
+* `push`, `pull`, `pre`, `post`, and `squish` add margin left/right shortcuts.
+
+Removed:
+
+* `alpha` and `full` are no longer needed!
+* The poorly named `un-column` and `reset-column` have been replaced
+once-and-for-all with `reset-columns` (to match the `columns` mixin).
+
+**Upgrade**:
+
+# Remove any mention of 'alpha' and 'full' in your code. In some cases you
+ will want to replace 'full' with a simple `clear: both;`.
+# Replace any mention of 'un-column' or 'reset-column' with 'reset-columns'.
+# Any time 'columns' and 'omega' are declared in the same block, they can now be joined together. `@include columns(3); @include omega();` can become `@include columns(3 omega)`.
+
+You're done! Stop worrying about all that "nested vs. root" bullshit, and start playing with the new toys!
+
v0.9 [Apr 25 2011]
------------------
View
308 README.mkdn
@@ -4,15 +4,23 @@ Susy - Compass Plugin
Susy is a semantic CSS grid system for designers.
Use Susy anywhere. Static sites, Rails sites, Django sites, PHP sites,
-etc. You name it. Susy just helps you with the grid - whether you want it
-fixed, fluid, elastic or Susy's specialty: fluid on the inside and elastic on
-the outside. And Susy will do it all without ever touching your markup.
+etc. You name it. Susy just helps you with the grid - without ever touching
+your markup.
+
+Melts in the mouth
+------------------
+
+Susy grids are always fluid on the inside, but contained in the candy shell of
+your choice (fixed/fluid/elastic). That allows them to flex, react, and move
+as needed.
Built entirely native to [Compass](http://compass-style.org/), Susy is based
on the philosophy and techniques of [Natalie Downe](http://natbat.net/)'s
-"[CSS Systems](http://natbat.net/2008/Sep/28/css-systems/)" - which introduces
-difficult math in return for beautiful structure. Now Susy will do that math
-for you and let you focus on your designs.
+"[CSS Systems](http://www.slideshare.net/nataliedowne/css-systems-presentation)
+" - which introduces difficult math in return for beautiful structure and
+flexibility.
+
+Susy will do all the math, and let you focus on your designs.
Install
=======
@@ -24,257 +32,79 @@ Create a Susy-based Compass Project
compass create <project name> -r susy -u susy
-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:
-
-* Able to control our designs and line-lengths with some amount of precision.
-
-* 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 goals 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) and important mixins in `_base.scss`.
-
- Example:
-
- $total-cols: 12; /* a 12-column grid */
- $col-width: 4em; /* each column is 4em wide */
- $gutter-width: 1em; /* 1em gutters between columns */
- $side-gutter-width: $gutter-width; /* 1em padding at the edges of the page as well */
-
-* Create your grid in `screen.scss`: apply the `container` mixin to the
- element(s) that contains the page grid. This will set up your font sizes
- and grid container.
-
- Example:
-
- #page {
- @include container;
- }
-
- CSS Output:
-
- #page {
- *zoom: 1;
- margin: auto;
- width: 61em;
- max-width: 100%;
- }
- #page:after {
- content: "\0020";
- display: block;
- height: 0;
- clear: both;
- overflow: hidden;
- visibility: hidden;
- }
-
-* 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.
-
- There is an important distinction between "root" and "nested" contexts in
- Susy. There is also a distinction between "grid elements" and "non-grid
- elements". Grid elements are any elements that you assign a span to, either
- with the `columns` or `full` mixin. Non-Grid elements include everything
- else. Just as CSS absolute positioning happens in relation to the nearest
- positioned ancestor, Susy grid "context" depends on the nearest grid-element
- ancestor. Any element with the `container` as it's nearest grid ancestor is
- considered to be in the "root" context. Any element within other grid
- elements (with a nearest grid ancestor other than the `container`) is
- considered to be in a "nested" context.
-
- This is important because side-gutters are handled at the root level, as
- margins on root grid elements. Margins that we don't want at nested levels.
- It is also important because Susy grid elements are %-based, and so the
- context is important to Susy's math. `Full` is simply a shortcut to replace
- `columns` when the span should be the full width.
-
- The `columns` mixin:
-
- @include columns($span, [$context]);
-
- The `full` mixin:
-
- @include full([$context]);
-
- *Note:* Context _must not_ be passed at the root level, and _must_ be passed at nested levels.
-
-* Use `alpha` and `omega` to declare elements which include
- the first or last column within their parent element.
-
- *Note:* `alpha` is _only_ needed in the root level, and does
- nothing in nested contexts. Neither is needed with an `full` element.
-
- The `alpha` and `omega` mixins:
-
- @include alpha;
- @include omega([$context]);
-
- Example Scss:
-
- #page {
- @include container;
- header {
- @include full;
- h1 {
- @include full(12);
- }
- }
- nav {
- @include columns(3);
- @include alpha;
- }
- #content {
- @include columns(9);
- @include omega;
- #main {
- @include columns(6,9);
- }
- aside {
- @include columns(3,9);
- @include omega(9);
- }
- }
- }
-
- Susy's CSS output uses floats to arrange the columns, widths to set the
- spans, right-margins to set the getter, and both side margins to set the
- side-gutters on root `alpha` and `omega` elements.
-
-* Use `prefix` or `suffix` to pad (in columns) the width of
- an element using left and right padding, or `pad` to give both `prefix` and
- `@suffix` at once.
-
- The `prefix`, `suffix` and `pad` mixins:
-
- @include prefix($prefix-span [, $context])
- @include prefix($suffix-span [, $context])
- @include pad($prefix-span, $suffix-span [, $context])
-
- Used with `full` these are subtractive, so the full width remains:
-
- header {
- @include full;
- @prefix(2);
- }
-
- Will result in a full-width element, with 2 columns of padding to the left.
-
- Used with `columns` these are addative, so the content width remains:
-
- aside {
- @include columns(3,9);
- @prefix(3,9)
- }
-
- Will result in a 6-column element, with 3 of those columns used as padding
- on the left.
-
-That's it for the basics! Here's a sample Susy grid layout:
-
- #page {
- @include container;
- }
-
- header {
- @include full;
- @include pad(1,1);
+_(This now refers to the unreleased 1.0 version of Susy.)_
- h1 {
- @include full(10);
- }
- }
+* Settings:
- nav {
- @include columns(3);
- @include alpha;
- }
+ Set up your default grid values: total columns, column width, gutter width,
+ and side-gutter width.
- #content {
- @include columns(9);
- @include omega;
- #main {
- @include columns(6,9);
- }
- aside {
- @include columns(3,9);
- @include omega(9);
- }
- }
+```scss
+$total-cols : 12; /* a 12-column grid */
+$col-width : 4em; /* each column is 4em wide */
+$gutter-width : 1em; /* 1em gutters between columns */
+$side-gutter-width : $gutter-width; /* 1em padding on the entire grid */
+```
-Tutorial
-========
+* Mixins:
+
+ The basic grid is composed using two simple mixins:
+ * Apply the `container` mixin to create your initial grid context.
+ * Apply the `columns` mixin to declare the width of an element on the grid.
-Check out the tutorial at [susy.oddbird.net/tutorial/](http://susy.oddbird.net/tutorial/) for more details.
+ Use the 'omega' trigger to declare elements that span the _final_ column of
+ their parent element, and pass a 'context' in nested situations. The
+ 'context' for any element is equal to the number of columns spanned by it's
+ parent.
-Show your grids
-===============
+For example:
-* `@include susy-grid-background` - For testing it can be helpful to see your
-grid. Using CSS3 gradients, Susy will show you that grid - and it will flex
-right along with your site.
+```scss
+#page {
+ @include container;
-Advanced Options
-================
+ /*
+ full-width items like the header don't need any help from Susy:
+ header { ... }
+ */
-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 are a few:
+ nav { @include columns(3); }
-* `gutter($context)` is a function that you can call at any time to return the
- size of a gutter in your given context as a percentage.
+ #content {
+ @include columns(9 omega);
- Example:
+ #main { @include columns(6,9); }
+ aside { @include columns(3 omega,9); }
+ }
- #nav {
- padding-right: gutter(5);
- }
+ footer { clear: both; }
+}
+```
-* `columns($number, $context)` returns the span of `$number` columns in
- `$context` as a percentage. This span includes any gutters between the
- columns spanned. `column($context)` is also available as a single-column
- shortcut.
+Layouts and Breakpoints
+-----------------------
- Example:
+The point is to change layouts (number of columns in the grid) at breakpoints. If you supply only a breakpoint, Susy will supply the closest layout. If you supply only a layout, Susy will provide the closest breakpoint.
- #nav {
- padding-left: columns(3,5);
- }
+```scss
+/* Switch to a 12-column grid when there is room for one. */
+@include at-breakpoint(12) {
+ .container { @include container; }
+}
-* `side_gutter()` returns the percentage width of a side-gutter and takes no
- arguments since it can always used at the top nesting level.
+/* At a min-width of 30em, switch to the nearest fitting layout. */
+@include at-breakpoint(30em) {
+ .container { @include container; }
+}
-Susy now also supports right-to-left and bi-directional documents. For a
-simple toggle, set the default `$from-direction` (defaults to `left`). For
-more specific control, you can pass an additional, localized `$from-direction`
-argument to any of the Susy mixins that need to know:
+/* Between the min-width of 30em and the max-width of 60em, use a 10-column layout. Provide a fallback class for IE. */
+@include at-breakpoint(30em 10 60em ie) {
+ .container { @include container; }
+}
-* `columns`, `reset-column`
-* `alpha`, `omega`
-* `prefix`, `suffix`, `pad`
+/* Create all your container layouts in one go. Each argument accepts min/layout/max/ie, same as at-breakpoint. */
+.container { @include container(4,8,12); }
+```

0 comments on commit be80157

Please sign in to comment.