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);
}

Just popping in to say I wrote a quick function that can make some natural language parsing work pretty well: https://github.com/ericam/susy/blob/susy2_math-engine/sass/susy/_math.scss#L24

Still issues with identifying the unperfected span number in code. Would love to think about this stuff without worrying about how it can be parsed, I’m sure we can make something work and user-facing stuff seems most important. But Susy is an interface for math and there is a lot of code we should be thinking about now.

+1 @Snugug on other points.

Agreed on all counts, with some questions still remaining :). Great write-up @Snugug. @scottkellum, I'll have to play with that function to understand it better, but it looks sweet. Thanks!

I agree that we should always allow as much as possible, while pushing best-practice defaults. The current defaults are a legacy problem, not a decision to push desktop-first approach. I'm also certain we will need at least most of the global settings mentioned, and possibly a few more. Mainly I'm interested in determining each feature we need to handle, and then the best way to handle it at each level (local & global) as needed. I think we're on track for that.

I don't think anyone has proposed that float/isolate should be automatic. We all agree that output should be explicit in every way. It's just a matter of nailing down how each feature is stated.

As I understand, here are the arguments that we need (and some proposals for how they might work):

• Arbitrary width: 30% or 30em or 300px (easy!)
• Uniform column span, with optional context: 3 or 3 of 6
• Non-uniform column span, with location-select and optional context: 3 at 3 or 3 at 4 of 12
• Pushing & pulling: push 4 or pull 3
• Isolated location: isolate 4

More on isolation:

Isolation is not an entirely distinct grid output type, it's simply a way of moving your columns around. It is the "absolute" alternative to the more "relative" push/pull. It's a local decision, not a global one. Here's two reasons:

1. Since isolation requires an extra argument on each element anyway, I don't see any reason for a global setting. If the argument is passed, you want isolation, if it isn't, you want floats. That's not automatic, it's explicitly called with it's own syntax:

$output: isolate;

// this is required either way (with or without the global setting), and works fine without it.
// the global setting has accomplished absolutely nothing.
.thing { @include span(3 isolate 4); } 

1. It's bad for the flow, requires extra markup & css, and is basically a hack. We should not be pushing this as a global setting - we should be pushing it as an option you use in the few cases where it really can help.

More on non-uniform location-selection (which column widths to use):

I'm not entirely convinced that <span> at <location> is the best syntax for working with non-uniform grids. I was never suggesting that we use at for both location and isolation - only that I think it works better as an isolation syntax than it does as a location syntax. To me, it seems strange to define non-uniform spans based on their count and starting-point. We don't actually care how many are spanned (and neither does the user) - what matters is where we start and where we end. Why not base the syntax on start and finish, rather than start and count? We could use <start> to <end>?

// Say we want to span columns 4-7 (3 columns) of a non-uniform 12-column grid

// your proposed syntax takes start (4) and count (3):
.thing { @include span(3 at 4); }

// my syntax doesn't care how many - only where we start (4) and where we end (7):
.thing { @include span(4 to 7); }

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.

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.