The Su Math Layer

susy-sass3 is built in two layers. The Susy layer is the syntax-sugar you’ve seen so far — global defaults, shorthand parsing, and normalization. Underneath it sits Su, the core grid-math engine: a handful of “pure” functions that expect fully-normalized values and do the actual calculations.

If you prefer named arguments to shorthand, or you’re building your own susy-sass3 extensions, you can call the Su functions directly in place of span, gutter, and slice.

Note

The Su functions do no shorthand parsing or normalization. Columns must be a real list, gutters a real number, spread a number (-1 / 0 / 1, corresponding to narrow / wide / wider… see below), and so on. If you want the friendly syntax, use the Susy layer or the plugin helpers.

---

A Note on Spread

At the Su layer, spread is expressed as a number rather than a keyword:

• -1 — narrow (gutters between columns only)

• 0 — wide (one side gutter)

• 1 — wider (a side gutter on both ends)

The Susy layer translates the narrow / wide / wider keywords into these numbers for you.

---

Su Span

Return a CSS-ready span width from normalized values.

function

Format:

su-span($span, $columns, $gutters, $spread, $container-spread: $spread, $location: 1)

$span:

<number> | <list> — columns to span

$columns:

<list> — the available columns

$gutters:

<number> — gutter width in column-comparable units

$spread:

-1 | 0 | 1

$container-spread:

[optional] -1 | 0 | 1

$location:

[optional] position of the span among the columns

This is the low-level version of span.

• Unitless grids return % values.

• Grids in comparable units return a value in those units.

• Grids that mix units (or fractions with lengths) return a calc() string.

// 3 of 6 fluid columns, 0.25 gutter, narrow spread
.foo { width: su-span(3, (1 1 1 1 1 1), 0.25, -1); }

---

Su Gutter

Return a CSS-ready gutter width from normalized values.

function

Format:

su-gutter($columns, $gutters, $container-spread)

$columns:

<list> — the columns in the grid

$gutters:

<number> — gutter width in column-comparable units

$container-spread:

-1 | 0 | 1

The low-level version of gutter, following the same unit rules as su-span.

.foo { margin-left: su-gutter((1 1 1 1 1 1), 0.25, -1); }

---

Su Slice

Return a sub-list of columns for a nested context.

function

Format:

su-slice($span, $columns, $location: 1, $validate: true)

$span:

<number> — number of columns to span

$columns:

<list> — the columns in the grid

$location:

[optional] starting index (1-based)

$validate:

[optional] validate arguments first

The low-level version of slice. Location is a 1-based column index — 1 is the first column.

// 3 columns starting at index 3
$context: su-slice(3, (1 2 3 5 8), 3);

// result
/* $context: 3 5 8; */

---

Build Something New

Because the math layer is fully abstract, you can wrap it in any syntax you like — port the language of another grid tool, or invent your own. The plugin helpers (susy-compile and su-call) are the recommended bridge: let them handle parsing and normalization, then hand the result to Su.

@function my-span($short, $config: ()) {
  $data: susy-compile($short, $config);
  @return su-call('su-span', $data);
}

.foo { width: my-span(3 of 6); }

That’s really all it takes to build a grid system. The rest is just syntax. Now go build yourself one!