Susy One¶

This is documentation for the old syntax, used in Susy 1.

If you are using Susy 2 and want use the old syntax, change your import from susy to susyone.

// With Susy 2 installed...
@import "susyone";

Basic Settings¶

Container: The root element of a Grid.
Layout: The total number of Columns in a grid.
Grid Padding: Padding on the sides of the Grid.
Context: The number of Columns spanned by the parent element.
Omega: Any Grid Element spanning the last Column in its Context.

Total Columns¶

The number of Columns in your default Grid Layout.

// $total-columns: <number>;
$total-columns: 12;

<number>: Unitless number.

Column Width¶

The width of a single Column in your Grid.

// $column-width: <length>;
$column-width: 4em;

<length>: Length in any unit of measurement (em, px, %, etc).

Gutter Width¶

The space between Columns.

// $gutter-width: <length>;
$gutter-width: 1em;

<length>: Units must match $column-width.

Grid Padding¶

Padding on the left and right of a Grid Container.

// $grid-padding: <length>;
$grid-padding: $gutter-width;  // 1em

<length>: Units should match the container width ($column-width unless $container-width is set directly).

Functions¶

Where a mixin returns property/value pairs, functions return simple values that you can put where you want, and use for advanced math.

Columns¶

Similar to span-columns mixin, but returns the math-ready % multiplier.

// columns(<$columns> [, <$context>, <$style>])
.item { width: columns(3,6); }

<$columns>: The number of Columns to span,
<$context>: The Context. Default: $total-columns.
<$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Gutter¶

The % width of one gutter in any given context.

// gutter([<$context>, <$style>])
.item { margin-right: gutter(6) + columns(3,6); }

<$context>: The Context. Default: $total-columns.
<$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Space¶

Total % space taken by Columns, including internal AND external gutters.

// space(<$columns> [, <$context>, <$style>])
.item { margin-right: space(3,6); }

<$columns>: The number of Columns to span,
<$context>: The Context. Default: $total-columns.
<$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Basic Mixins¶

Container¶

Establish the outer grid-containing element.

// container([$<media-layout>]*)
.page { @include container; }

<$media-layout>: Optional media-layout shortcuts (see Responsive Grids below). Default: $total-columns.

Span Columns¶

Align an element to the Susy Grid.

// span-columns(<$columns> [<omega> , <$context>, <$padding>, <$from>, <$style>])
nav { @include span-columns(3,12); }
article { @include span-columns(9 omega,12); }

<$columns>: The number of Columns to span. - <omega>: Optional flag to signal the last element in a row.
<$context>: Current nesting Context. Default: $total-columns.
<$padding>: Optional padding applied inside an individual grid element. Given as a length (same units as the grid) or a list of lengths (from-direction to-direction). Default: false.
<$from>: The origin direction of your document flow. Default: $from-direction.
<$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Omega¶

Apply to any omega element as an override.

// omega([<$from>])
.gallery-image {
  @include span-columns(3,9); // each gallery-image is 3 of 9 cols.
  &:nth-child(3n) { @include omega; } // every third image completes a row.
}

<$from>: The origin direction of your document flow. Default: $from-direction.

Nth-Omega¶

Apply to any element as an nth-child omega shortcut. Defaults to :last-child.

// nth-omega([<$n>, <$selector>, <$from>])
.gallery-image {
  @include span-columns(3,9); // each gallery-image is 3 of 9 cols.
  @include nth-omega(3n); // same as omega example above.
}

<$n>: The keyword or equation to select: [first | only | last | <equation>]. An equation could be e.g. 3 or 3n or '3n+1'. Note that quotes are needed to keep complex equations from being simplified by Compass. Default: last.
<$selector>: The type of element, and direction to count from: [child | last-child | of-type | last-of-type ]. Default: child.
<$from>: The origin direction of your document flow. Default: $from-direction.

Responsive Mixins¶

Breakpoint: A min- or max- viewport width at which to change Layouts.
Media-Layout: Shortcut for declaring Breakpoints and Layouts in Susy.

// $media-layout: <min-width> <layout> <max-width> <ie-fallback>;
// - You must supply either <min-width> or <layout>.
$media-layout: 12;          // Use 12-col layout at matching min-width.
$media-layout: 30em;        // At min 30em, use closest fitting layout.
$media-layout: 30em 12;     // At min 30em, use 12-col layout.
$media-layout: 12 60em;     // Use 12 cols up to max 60em.
$media-layout: 30em 60em;   // Between min 30em & max 60em, use closest layout.
$media-layout: 30em 12 60em;// Use 12 cols between min 30em & max 60em.
$media-layout: 60em 12 30em;// Same. Larger length will always be max-width.
$media-layout : 12 lt-ie9;  // Output is included under ``.lt-ie9`` class,
                            // for use with IE conditional comments
                            // on the <html> tag.

<$min/max-width>: Any length with units, used to set media breakpoints.
<$layout>: Any (unitless) number of columns to use for the grid at a given breakpoint.
<$ie-fallback>: Any string to use as a fallback class when mediaqueries are not available. Do not include a leading “.” class-signifier, only the class name (“lt-ie9”, not “.lt-ie9”). This can be anything you want: “no-mediaqueries”, “ie8”, “popcorn”, etc.

At-Breakpoint¶

At a given min- or max-width Breakpoint, use a given Layout.

// at-breakpoint(<$media-layout> [, <$font-size>]) { <@content> }
@include at-breakpoint(30em 12) {
  .page { @include container; }
}

<$media-layout>: The Breakpoint/Layout combo to use (see above).
<$font-size>: Browsers interpret em-based media-queries using the browser default font size (16px in most cases). If you have a different base font size for your site, we have to adjust for the difference. Tell us your base font size, and we’ll do the conversion. Default: $base-font-size.
<@content>: Nested @content block will use the given Layout.

Layout¶

Set an arbitrary Layout to use with any block of content.

// layout(<$layout-cols>) { <@content> }
@include layout(6) {
  .narrow-page { @include container; }
}

<$layout-cols>: The number of Columns to use in the Layout.
<@content>: Nested @content block will use the given Layout.

Set Container Width¶

Reset the width of a Container for a new Layout context. Can be used when container() has already been applied to an element, for DRYer output than using container again.

// set-container-width([<$columns>, <$style>])
@include container;
@include at-breakpoint(8) {
  @include set-container-width;
}

<$columns>: The number of Columns to be contained. Default: Current value of $total-columns depending on Layout.
<$style>: Optionally return static lengths for grid calculations. Default: $container-style.

With Grid Settings¶

Use different grid settings for a block of code - whether the same grid at a different breakpoint, or a different grid altogether.

// with-grid-settings([$<columns>, $<width>, <$gutter>, <$padding>]) { <@content> }
@include with-grid-settings(12,4em,1.5em,1em) {
  .new-grid { @include container; }
};

<$columns>: Overrides the $total-columns setting for all contained elements.
<$width>: Overrides the $column-width setting for all contained elements.
<$gutter>: Overrides the $gutter-width setting for all contained elements.
<$padding>: Overrides the $grid-padding setting for all contained elements.
<@content>: Nested @content block will use the given grid settings.

Box Sizing¶

Border-Box Sizing¶

Set the default box-model to border-box, and adjust the grid math accordingly.

// border-box-sizing()
@include border-box-sizing;

This will apply border-box model to all elements (using the star selector) and set $border-box-sizing to true. You can use the variable on it’s own to adjust the grid math, in cases where you want to apply the box-model separately.

Isolation¶

Isolate¶

Isolate the position of a grid element relative to the container. This should be used in addition to span-columns as a way of minimizing sub-pixel rounding errors in specific trouble locations.

// isolate(<$location> [, <$context>, <$from>, <$style>])
@include span-columns(4); // 4-columns wide
@include isolate(2); // positioned in the second column

<$location>: The container-relative column number to position on.
<$context>: Current nesting Context. Default: $total-columns.
<$from>: The origin direction of your document flow. Default: $from-direction.
<$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Isolate Grid¶

Isolate a group of elements in a grid (such as an image gallery) using nth-child or nth-of-type for positioning. Provide the column-width of each element, and Susy will determine the positioning for you.

// isolate-grid(<$columns> [, <$context>, <$selector>, <$from>, <$style>])
.gallery-item {
  @include isolate-grid(3);
}

<$columns>: The number of Columns for each item to span.
<$context>: Current nesting Context. Default: $total-columns.
<$selector>: either ‘child’ or ‘of-type’. Default: child.
<$from>: The origin direction of your document flow. Default: $from-direction.
<$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Padding Mixins¶

Prefix¶

Add Columns of empty space as padding before an element.

// prefix(<$columns> [, <$context>, <$from>, <$style>])
.box { @include prefix(3); }

<$columns>: The number of Columns to be added as padding before.
<$context>: The Context. Default: $total-columns.
<$from>: The origin direction of your document flow. Default: $from-direction.
<$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Suffix¶

Add columns of empty space as padding after an element.

// suffix(<$columns> [, <$context>, <$from>, <$style>])
.box { @include suffix(2); }

<$columns>: The number of Columns to be added as padding after.
<$context>: The Context. Default: $total-columns.
<$from>: The origin direction of your document flow. Default: $from-direction.
<$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Pad¶

Shortcut for adding both Prefix and Suffix padding.

// pad([<$prefix>, <$suffix>, <$context>, <$from>, <$style>])
.box { @include pad(3,2); }

<$prefix>: The number of Columns to be added as padding before.
<$suffix>: The number of Columns to be added as padding after.
<$context>: The Context. Default: $total-columns.
<$from>: The origin direction of your document flow. Default: $from-direction.
<$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Bleed¶

Add negative margins and matching positive padding to an element, so that its background “bleeds” outside its natural position.

// bleed(<$width> [<$sides>, <$style>])
@include bleed(2);

<$width>: The number of Columns or arbitrary length to bleed. Use 2 of 12 syntax for context in nested situations.
<$sides>: The sides of the element that should bleed. Default: left right.
<$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Margin Mixins¶

Pre¶

Add columns of empty space as margin before an element.

// pre(<$columns> [, <$context>, <$from>, <$style>])
.box { @include pre(2); }

<$columns>: The number of Columns to be added as margin before.
<$context>: The Context. Default: $total-columns.
<$from>: The origin direction of your document flow. Default: $from-direction.
<$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Post¶

Add columns of empty space as margin after an element.

// post(<$columns> [, <$context>, <$from>, <$style>])
.box { @include post(3); }

<$columns>: The number of Columns to be added as margin after.
<$context>: The Context. Default: $total-columns.
<$from>: The origin direction of your document flow. Default: $from-direction.
<$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Squish¶

Shortcut to add empty space as margin before and after an element.

// squish([<$pre>, <$post>, <$context>, <$from>, <$style>])
.box { @include squish(2,3); }

<$pre>: The number of Columns to be added as margin before.
<$post>: The number of Columns to be added as margin after.
<$context>: The Context. Default: $total-columns.
<$from>: The origin direction of your document flow. Default: $from-direction.
<$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Push¶

Identical to pre.

// push(<$columns> [, <$context>, <$from>, <$style>])
.box { @include push(3); }

Pull¶

Add negative margins before an element, to pull it against the flow.

// pull(<$columns> [, <$context>, <$from>, <$style>])
.box { @include pull(2); }

<$columns>: The number of Columns to be subtracted as margin before.
<$context>: The Context. Default: $total-columns.
<$from>: The origin direction of your document flow. Default: $from-direction.
<$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Reset Mixins¶

Reset Columns¶

Resets an element to default block behaviour.

// reset-columns([<$from>])
article { @include span-columns(6); }     // articles are 6 cols wide
#news article { @include reset-columns; } // but news span the full width
                                          // of their container

<$from>: The origin direction of your document flow. Default: $from-direction.

Remove-Omega¶

Apply to any previously-omega element to reset it’s float direction and margins to match non-omega grid elements. Note that unlike omega, this requires a context when nested.

// remove-omega([<$context>, <$from>, <$style>])
.gallery-image {
  &:nth-child(3n) { @include remove-omega; } // 3rd images no longer complete rows.
}

<$context>: Current nesting Context. Default: $total-columns.
<$from>: The origin direction of your document flow. Default: $from-direction.
<$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Remove Nth-Omega¶

Apply to any previously nth-omega element to reset it’s float direction and margins to match non-omega grid elements. Note that unlike omega, this requires a context when nested.

// remove-nth-omega([<$n>, <$selector>, <$context>, <$from>, <$style>])
.gallery-image {
  @include remove-nth-omega(3n); // same as remove-omega example above.
}

<$n>: The keyword or equation to select: [first | only | last | <equation>]. An equation could be e.g. 3 or 3n or '3n+1'. Note that quotes are needed to keep a complex equation from being simplified by Compass. Default: last.
<$selector>: The type of element, and direction to count from: [child | last-child | of-type | last-of-type ]. Default: child.
<$context>: Current nesting Context. Default: $total-columns.
<$from>: The origin direction of your document flow. Default: $from-direction.
<$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Debugging¶

Susy Grid Background¶

Show the Susy Grid as a background-image on any container.

// susy-grid-background();
.page { @include susy-grid-background; }

If you are using the <body> element as your Container, you need to apply a background to the <html> element in order for this grid-background to size properly.
Some browsers have trouble with sub-pixel rounding on background images. Use this for checking general spacing, not pixel-exact alignment. Susy columns tend to be more accurate than gradient grid-backgrounds.

Container Override Settings¶

Container Width¶

Override the total width of your grid with an arbitrary length.

// $container-width: <length> | <boolean>;
$container-width: false;

<length>: Length in em, px, %, etc.
<boolean>: True or false.

Container Style¶

Override the type of shell containing your grid.

// $container-style: <style>;
$container-style: magic;

<style>: magic | static | fluid.
- magic: Susy’s magic grid has a set width, but becomes fluid rather than overflowing the viewport at small sizes.
- static: Susy’s static grid will retain the width defined in your settings at all times.
- fluid: Susy’s fluid grid will always be based on the viewport width. The percentage will be determined by your grid settings, or by $container-width, if either is set using % units. Otherwise it will default to auto (100%).

Direction Override Settings¶

From Direction¶

The side of the Susy Grid from which the flow starts. For ltr documents, this is the left.

// $from-direction: <direction>;
$from-direction: left;

<direction>: left | right

Omega Float¶

The direction that Omega elements should be floated.

// $omega-float: <direction>;
$omega-float: opposite-position($from-direction);

<direction>: left | right

Compass Options¶

Base Font Size¶

From the Compass Vertical Rhythm module, Susy uses your base font size to help manage em-based media-queries.

// $base-font-size: <px-size>;
$base-font-size: 16px;

<px-size>: Any length in px. This will not actually effect your font size unless you use other Vertical Rhythm tools, we just need to know. See Compass Docs for further usage details.

Browser Support¶

Susy recognizes all the Compass Browser Support variables, although only IE6 and IE7 have special cases attached to them currently.

// $legacy-support-for-ie  : <boolean>;
// $legacy-support-for-ie6 : <boolean>;
// $legacy-support-for-ie7 : <boolean>;
$legacy-support-for-ie  : true;
$legacy-support-for-ie6 : $legacy-support-for-ie;
$legacy-support-for-ie7 : $legacy-support-for-ie;

<boolean>: true | false

Breakpoint Output¶

If you are compiling seperate files for IE-fallbacks, it can be useful to output only the modern code in one file and only the fallbacks in another file. You can make at-breakpoint do exactly that by using the following settings.

$breakpoint-media-output¶

Turn off media-query output for IE-only stylesheets.

// $breakpoint-media-output: <boolean>;
$breakpoint-media-output: true;

<boolean>: true | false

$breakpoint-ie-output¶

Turn off media-query fallback output for non-IE stylesheets.

// $breakpoint-ie-output: <boolean>;
$breakpoint-ie-output: true;

<boolean>: true | false

$breakpoint-raw-output¶

Pass through raw output without media-queries or fallback classes for IE-only stylesheets.

// $breakpoint-raw-output: <boolean>;
$breakpoint-raw-output: false;

<boolean>: true | false