Why susy-sass3 Is Just Functions

If you’ve used an older grid framework — including Susy 1 or Susy 2 — the first thing you’ll notice about susy-sass3 is what’s missing: there are no mixins, no container element, no output modes, no breakpoint helpers. Just three functions (span, gutter, and slice) and four settings.

That’s a deliberate design, and this page explains the thinking behind it, so the rest of the docs make sense.

Note

This functions-only design is the Susy 3 architecture originally created by Miriam Eric Suzanne and OddBird. susy-sass3 continues it on Dart Sass; the explanation here is written for this fork.

The web changed underneath grid frameworks

Grid frameworks were born in an era when laying out a page meant fighting the browser: float clearing, box-model inconsistencies, and a pile of hacks just to get columns to line up. A library that hid all of that behind a mixin was a genuine relief.

That era is over. Modern browsers give us real layout tools — flexbox and CSS Grid — with alignment and flexibility built in, plus a predictable box model. When the browser can do the hard part, a framework that wraps everything in its own mixins stops being a help and starts being something extra to learn and work around.

So susy-sass3 does less on purpose. It doesn’t try to be your layout system. It gives you the grid math, and lets you apply it with whatever layout technique you’re already using.

The trouble with mixins

Susy 1 and Susy 2 leaned on mixins because, at the time, floats were effectively the only game in town and they needed a lot of help. A mixin like @include span(3 of 12) was convenient, but it came with two costs:

It hid the CSS. You couldn’t see what properties were being set, which made output hard to predict and harder to debug.
It locked you into one technique. The mixin decided you were floating, and wrote floats — so it didn’t help if you wanted flexbox, grid, or something else.

A function has neither problem. span(3 of 12) returns a width and nothing else. You decide which property it lands on, and the CSS stays in plain sight:

// you can read exactly what this produces
.item {
  float: left;
  width: span(3 of 12);          // 23.72881%
  margin-right: gutter(of 12);   // 1.69492%
}

Yes, it’s a little more typing than a mixin. In return, nothing is hidden, and the same function works no matter how you build the layout.

Grid math, only where you need it

The core idea is grid-math-on-demand: instead of building a whole system of classes or mixins up front, reach for a function at the exact spot you need to align something to the grid.

The same span() result drops into any layout technique:

// floats
.float {
  width: span(3);
  margin-right: gutter();
}

// flexbox — use span() as the flex-basis
.flexbox {
  flex: 1 1 span(3);
  padding: 0 gutter() / 2;
}

// pushing and pulling with margins
.push-3 { margin-left: span(3 wide); }
.pull-3 { margin-left: 0 - span(3 wide); }

If you do want a reusable pattern, you can still build your own thin mixin or utility-class set on top of the functions — susy-sass3 just doesn’t force one on you. See the plugin helpers for building extensions.

Settings that echo CSS Grid

The settings were deliberately shaped to look like native CSS Grid, so what you learn here transfers to the platform:

columns takes a list of column sizes, like grid-template-columns. Unitless numbers behave like the fr unit, and susy-repeat() mirrors the CSS repeat() function.
gutters is a single length or fraction, much like grid-column-gap.

// CSS Grid
// grid-template-columns: repeat(12, 120px);

// susy-sass3
$susy: ('columns': susy-repeat(12, 120px));

Because Sass has no access to the browser’s box model, susy-sass3 emits calc() output automatically when a grid mixes units it can’t reconcile ahead of time (say, static px columns beside fluid fractions).

When you don’t need susy-sass3 at all

In the spirit of doing less, it’s worth saying plainly: if your browser support allows it, native CSS Grid is often the better answer, and you may not need susy-sass3 for that layout.

A couple of rules of thumb:

If you can drop margin-gutters — or move gutters into padding — the math collapses into a plain fraction, and you may not need any tool:
```
.simple {
  float: left;
  width: percentage(3 / 12);  // no gutters to account for
}
```
Flexbox is frequently enough on its own, since it expresses relationships (equal-height columns, centering) rather than explicit track widths.

susy-sass3 earns its place in the harder cases: margin-gutters, asymmetrical grids, and mixed-unit calculations that are genuinely awkward to do by hand. That’s where turning a gnarly fraction into span(3) actually pays off.

From here, the Settings, Shorthand, and Toolkit pages cover the details, and Understanding Spread explains the one concept most worth understanding.