Upgrade Path

susy-sass3 is a ground-up rethink of Susy 2. If you’re coming from Susy 2 (or the older Susy 1), this is a significant change — but the result is much smaller and more flexible. This page covers the highlights. For the reasoning behind the redesign, see Why susy-sass3 Is Just Functions, and for the trickiest concept, Understanding Spread.

No More Mixins

The biggest change: susy-sass3 has no mixins. span, container, gutters, last, gallery, bleed, isolate, show-grid, susy-breakpoint, and the rest have all been removed. Web layout has grown too powerful and flexible to wrap up in a fixed set of shortcuts.

Instead, susy-sass3 gives you three functions — span, gutter, and slice — and you apply their return values yourself. What used to be a mixin becomes a couple of plain CSS declarations:

// Susy 2
.item { @include span(3 of 12); }

// susy-sass3 — you write the output
.item {
  float: left;
  width: span(3 of 12);
  margin-right: gutter(of 12);
}

This is more typing for a floated grid, but it also means susy-sass3 works just as well with flexbox, CSS grid, transforms, or anything else — it never assumes how you want to build your layout.

Settings

susy-sass3 trims the settings down to four: columns, gutters, spread, and container-spread. Most of the Susy 2 settings are simply gone.

Columns

columns no longer takes a bare number. Describe your grid as a list of column sizes, using susy-repeat() for equal columns:

// Susy 2
$susy: (columns: 12);

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

The old $count x $width syntax for static grids is likewise replaced:

// Susy 2:  columns: 4 x 120px
// susy-sass3
$susy: ('columns': susy-repeat(4, 120px));

Math, Output, Container, Flow…

There’s no math, output, container, container-position, flow, last-flow, gutter-position, global-box-sizing, debug, or use-custom setting anymore. Because susy-sass3 only returns values and never writes layout CSS, most of these no longer have anything to configure.

Fluid vs static is now decided by your units. Unitless columns produce % output; united columns produce that unit; mixing them produces calc().
Gutter position (before / after / inside / split) was about where a mixin wrote margins or padding. Now you decide that yourself by choosing which property to apply gutter() to.
Flow / direction is handled with your own CSS (or logical properties).

Spread

spread existed in Susy 2 as a per-span option (narrow / wide / wider) and was otherwise handled behind the scenes. susy-sass3 promotes it to a first-class setting, with a matching container-spread, giving you full control over the edge gutters at both ends. See Understanding Spread.

Functions

Span & Gutter

The span and gutter functions carry over, using the shorthand syntax. The old columns() and space() functions are gone — the narrow / wide spread keywords cover that difference now.

// Susy 2
$a: columns(3, 6);
$b: space(2, 7);

// susy-sass3
$a: span(3 of 6);
$b: span(2 of 7 wide);

Container & Isolation

There’s no container function or mixin, and no isolation output — those were tied to specific layout techniques. Set your own container width, and use modern layout tools (flexbox, grid) to avoid the sub-pixel issues isolation worked around.

Debugging Grids

The Susy 2 show-grid mixin and debug settings are replaced by susy-sass3’s SVG Grid plugin. Import it and drop the returned SVG into a background:

@import 'susy-sass3/sass/plugins/svg-grid';

.grid { background: susy-svg-grid() no-repeat scroll; }

Responsive Design

Media-query handling has been removed entirely — there’s no susy-breakpoint or susy-media. susy-sass3 returns values, so you can call the functions inside any @media block (or any media-query library you already use):

.main { width: span(4 of 4); }

@media (min-width: 40em) {
  .main { width: span(3 of 12); }
}

Distribution & Toolchain

susy-sass3 is distributed on npm only now (no RubyGems or Bower). The package is susy-sass3.
susy-sass3 additionally moves the whole thing onto Dart Sass; the old node-sass / Compass toolchain is no longer supported.

See the Changelog for the full history.