about.md

About This Proposal

This is a very rough proposal for a radical Susy 2.0 API overhaul.

The basic goals are:

1. Flexible: Allow all the main layout approaches.

• float / isolation
• columns (symmetrical & asymmetrical) / fractions / explicit widths
• gutters inside or outside - before, after, or split

2. Simple: Less API is better.

• Less universal settings, everything can be controlled on-the-fly when possible
• Less mixins, with more power and flexibility

3. Moving Forward: Backwards functionality should be maintained.

• Anything you created in Susy 1.0 can be recreated in 2.0
• Layouts created in 1.0 do not need to work in 2.0 automatically

4. Light Touch: Always do the minimum possible to achieve a layout.

• If there's a question, less output is the answer.

5. Prepared: Plan ahead for flexbox & grid modules. (not considered yet in this proposal)

(Changes inspired largely by Singularity and Salsa, with elements from Zen as well.)

api.scss

// ----------------------------------------------------------------------------
// Settings

// $grid      : [<number> <settings> | <width> <complex-layout>] [inside | outside] [before | after | split];
// $direction : [left to right | right to left];

// Example: The current Susy default.
$grid         : 12 4em 1em 1em outside after;

// Example: The current Singularity demo.
$grid         : (1 2 3 5 2 3) .25;

// Example: The current Salsa default.
$grid         : 16 auto 20px inside split;

// ----------------------------------------------------------------------------
// Grid Container
//
// @include grid($width...)
// - $width   : <breakpoint> [static] <arbitrary with | column math>;
//            : 12 4em 1.5em               - Column math (explicit)
//            : 12 4em 1.5                 - Identical to above...
//            : break(25em) 8              - Breakpoint + column math (default)
//            : 60em                       - Arbitrary width
//            : static 60em                - Use 'width' instead of max-width

// Example: 4 column default width, breaks at 8 columns
.container { 
  @include grid(4, break(8)); 
}

// ----------------------------------------------------------------------------
// Grid-Spanning Element
//
// @include grid-span($width, $position)
// - $column    : [location | first, last <explicit>] [<width> | <columns-span> of <column-count> | <fraction>] [push <count> | pull <count>];
//              : first                    - Remove 'outside before' gutters
//              : last                     - Remove 'outside after' gutters (and reverse?)
//              : 3rd                      - Explicit location
//              : 2                        - Columns in context (root)
//              : 3 of 6                   - Columns in context (explicit)
//              : 2/6                      - Fraction
//              : push 3                   - Push
//              : pull 3                   - Pull
// - $modifiers : [reverse] [in <context>] [gutter | <width>] [margin | <margin>];
//              : reverse                  - Float the other direction
//              : in 960px                 - Modify column context
//              : in 75%                   - Modify column context
//              : gutter 2%                - Modify gutter
//              : margin 10px              - margins
//              : margin 6px 10px          - irregular margins

// Example: 4 of 10 Columns, pushed 3
.item {
  @include grid-span(4 of 12 push 3);
}

// Example: Same as above using a fraction
.item {
  @include grid-span(4/12 push 3);
}

// Example: Write a column of an arbitrary width.
.item {
  @include grid-span(30%);
}

// Example: second 3 of non-uniform Columns pushed 1, new gutter .2
.item {
  @include grid-span(2nd 3 of (2 1 5 1 3 3) push 1, gutter .2);
}

// Example: second 3 of non-uniform Columns pushed 1, new gutter 16px
.item {
  @include grid-span(2nd 3 of (100px 60px auto 60px 140px 140px) push 1, in 960px gutter 16px);
}

// Example: Same as above, assuming global grid is OK.
.item {
  @include grid-span(2nd 3 push 1);
}

// Example: span 5 columns assuming global grid, floats, and uniform columns
.item {
  @include grid-span(5);
}

I think we should decouple the idea of isolation and float. The reason I suggest that they are global settings is because:

1. We are not just dealing with float vs isolation, we want this system to eventually be able to do CSS grids, tables, etc…
2. Some people (like John and many Gridset users) will want to use Isolation for all of their items. It's a grid output style like any grid output style. I think we should keep it simply like that.