Sass Documentation

General Usage

If you're building your grid using the Sass mixins, there are a few things you should know.

  1. You should read up on how rows and columns work before attempting to use the mixins.
  2. By default media specific layouts are not applied. These need to be setup manually.

Before diving in to what each mixin does, here's a simple example:

<section>
  <article>Content</article>
  <aside>Sidebar</aside>
</section>
section {
  // Adds clearfix, centers the layout, and limits the fluid width
  @include row;

  article {
    // Creates an 9 unit wide column. $first removes the gutter on the left
    @include column(9, $first: true);
  }

  aside {
    // Creates a 3 unit wide column.
    @include column(3);
  }
}
section {
  margin-right: auto;
  margin-left: auto;
  padding-right: 20px;
  padding-left: 20px;
  max-width: 1060px;
}

section:before, section:after {
  display: table;
  content: " ";
}

section:after {
  clear: both;
}

section article {
  position: relative;
  display: block;
  float: left;
  min-height: 1px;
  width: 74.5283%;
}

section aside {
  position: relative;
  display: block;
  float: left;
  margin-left: 1.88679%;
  min-height: 1px;
  width: 23.58491%;
}

+row

Argument Description Default
$max‑width The max width of the row element. If this is false, the row is completely fluid. Value of $shelves‑max‑width
$margin The outer margins. Value of $shelves‑margin

The row mixin includes the styles for the row element. This includes a clearfix, widths, and centering.

.row {
  @include row($max-width: 1000px, $margin: 10px);
}
.row {
  margin-right: auto;
  margin-left: auto;
  padding-right: 10px;
  padding-left: 10px;
  max-width: 1000px;
}

.row:before, .row:after {
  display: table;
  content: " ";
}

.row:after {
  clear: both;
}

+row-base

The row-base mixin includes only the clearfix. Generally, you would use this mixin only on nested rows:

section {
  @include row;

  article {
    @include column(9, $first: true);

    header {
      @include row-base;

      h2 {
        @include column(6, 9, $first: true);
      }
    }
  }
}
section article header:before, section article header:after {
  display: table;
  content: " ";
}

section article header:after {
  clear: both;
}

+row-width

Argument Description Default
$max‑width The max width of the row element. If this is false, the row is completely fluid. Value of $shelves‑max‑width

Includes the max-width and centering for the rows.

section {
  @include row-width(1200px);
}
section {
  margin-right: auto;
  margin-left: auto;
  max-width: 1200px;
}

+row-margin

Argument Description Default
$margin The outer margins. Value of $shelves‑margin

Includes the styles for the outer margins of the row.

section {
  @include row-margin(25px);
}
section {
  padding-left: 25px;
  padding-right: 25px;
}

+reset-row

Reset a row completely, removing the width and outer margins. This is usually used in the context of nested rows or media specific changes. You can also reset only certain aspects of the row by using +reset-row-width or +reset-row-margin.

.row {
  @include row;

  .row {
    @include reset-row;
  }
}
.row .row {
  margin-right: 0;
  margin-left: 0;
  padding-right: 0;
  padding-left: 0;
  max-width: none;
}

+column

Argument Description Default
$n The number of columns the element should span.
$context The number of columns encapsulating the element. Value of $total
$first If true apply the +column-gutter mixin. false
$total The total number of columns in the grid. Value of $shelves‑columns
$gutter The width of the gutter in the root context (in %). Value of $shelves‑gutter

Creates a column that spans the given number of grid columns. Here's a simple example:

article {
  @include column(9);
}
article {
  position: relative;
  display: block;
  float: left;
  margin-left: 1.88679%;
  min-height: 1px;
  width: 74.5283%;
}

Now here's a more advanced example:

article {
  @include column(9, $first: true);

  header {
    @include row-base;

    h2 {
      // A 6 column element nested in a 9 column element.
      @include column(6, 9, $first: true)
    }

    img {
      // A 3 column element nested in a 9 column element.
      @include column(3, 9);
    }
  }
}

aside {
  @include column(3);
}

@include on-tablet-down {
  article {
    // A 4 column element in a tablet grid of 6 total columns.
    // Notice how the gutter is specified as well.
    @include column(4, $total: 6, $gutter: $shelves-tablet-gutter, $first: true);
  }

  aside {
    // A 2 column element in a tablet grid of 6 total columns.
    @include column(2, $total: 6, $gutter: $shelves-tablet-gutter);
  }
}
article {
  position: relative;
  display: block;
  float: left;
  min-height: 1px;
  width: 74.5283%;
}

article header h2 {
  position: relative;
  display: block;
  float: left;
  min-height: 1px;
  width: 65.82278%;
}

article header img {
  position: relative;
  display: block;
  float: left;
  margin-left: 2.53165%;
  min-height: 1px;
  width: 31.64557%;
}

aside {
  position: relative;
  display: block;
  float: left;
  margin-left: 1.88679%;
  min-height: 1px;
  width: 23.58491%;
}

@media screen and (max-width: 799px) {
  article {
    position: relative;
    display: block;
    float: left;
    min-height: 1px;
    width: 65.72327%;
  }

  aside {
    position: relative;
    display: block;
    float: left;
    margin-left: 2.83019%;
    min-height: 1px;
    width: 31.44654%;
  }
}

You may have noticed a good bit of duplication in the generated CSS of the former example. Take a look at the Best Practices to learn how to clean this up.

+column-base

Sets up an element to be a column in the grid system. Generally, this would be used in a placeholder to avoid duplication (see Best Practices).

article {
  @include column-base;
}
article {
  position: relative;
  display: block;
  float: left;
  min-height: 1px;
}

+column-width

Argument Description Default
$n The number of columns the element should span.
$context The number of columns encapsulating the element. Value of $total
$total The total number of columns in the grid. Value of $shelves‑columns
$gutter The width of the gutter in the root context (in %). Value of $shelves‑gutter

Sets the width of the element to the given number of columns.

article {
  @include column-width(9);

  aside {
    @include column-width(3, 9);
  }
}
article {
  width: 74.5283%;
}

article aside {
  width: 31.64557%;
}

+column-gutter

Argument Description Default
$context The number of columns encapsulating the element. Value of $total
$total The total number of columns in the grid. Value of $shelves‑columns
$gutter The width of the gutter in the root context (in %). Value of $shelves‑gutter

Includes the gutter for a column on the grid. The gutter is calculated based on the current $context. So if you're nested within a column, the column gutter will actually be larger (in percentage) to match the size of the default gutter.

article {
  @include column-width(9);
  @include column-gutter;

  aside {
    @include column-width(3, 9);
    @include column-gutter(9);
  }
}
article {
  margin-left: 1.88679%;
  width: 74.5283%;
}

article aside {
  margin-left: 2.53165%;
  width: 31.64557%;
}

+reset-column

Resets a column completely, returning it a default block element. This is useful if you'd like to reset a column in media specific situations. You can also reset only certain aspects of the column by using +reset-column-width, +reset-column-gutter, +reset-column-prefix, +reset-column-suffix, +reset-column-push, or +reset-column-pull.

@include on-mobile {
  article {
    @include reset-column;
  }
}
@media screen and (max-width: 479px) {
  article {
    right: auto;
    left: auto;
    float: none;
    margin-left: 0;
    padding-right: 0;
    padding-left: 0;
    width: auto;
  }
}

+on-desktop

Argument Description Default
$breakpoint The min-width to use a breakpoint. Value of $shelves‑tablet‑breakpoint
$columns The number of columns in the grid. Value of $shelves‑columns
$gutter The width of the gutter in the grid. Value of $shelves‑gutter

Media query shortcut for targeting only desktop device sizes (widths above the tablet breakpoint). This also sets the global column and gutter contexts to the desktop settings.

@include on-desktop {
  article {
    // $total is set to $shelves-columns
    // $gutter is set to $shelves-gutter
    @include column(5);
  }
}
@media screen and (min-width: 800px) {
  article {
    position: relative;
    display: block;
    float: left;
    margin-left: 1.88679%;
    min-height: 1px;
    width: 40.56604%;
  }
}

+on-tablet-up

Argument Description Default
$breakpoint The min-width to use a breakpoint. Value of $shelves‑mobile‑breakpoint
$columns The number of columns in the grid. Value of $shelves‑tablet‑columns
$gutter The width of the gutter in the grid. Value of $shelves‑tablet‑gutter

Media query shortcut for targeting only tablet & desktop device sizes (widths above the mobile breakpoint). This also sets the global column and gutter contexts to the tablet settings.

@include on-tablet-up {
  article {
    // $total is set to $shelves-tablet-columns
    // $gutter is set to $shelves-tablet-gutter
    @include column(5);
  }
}
@media screen and (min-width: 480px) {
  article {
    position: relative;
    display: block;
    float: left;
    margin-left: 2.83019%;
    min-height: 1px;
    width: 82.86164%;
  }
}

+on-tablet

Argument Description Default
$mobile‑breakpoint The min-width to use a breakpoint. Value of $shelves‑mobile‑breakpoint
$tablet‑breakpoint The max-width to use a breakpoint. Value of $shelves‑tablet‑breakpoint
$columns The number of columns in the grid. Value of $shelves‑tablet‑columns
$gutter The width of the gutter in the grid. Value of $shelves‑tablet‑gutter

Media query shortcut for targeting only tablet device sizes (widths between the mobile breakpoint and the tablet breakpoint). This also sets the global column and gutter contexts to the tablet settings.

@include on-tablet {
  article {
    // $total is set to $shelves-tablet-columns
    // $gutter is set to $shelves-tablet-gutter
    @include column(5);
  }
}
@media screen and (min-width: 480px) and (max-width: 799px) {
  article {
    position: relative;
    display: block;
    float: left;
    margin-left: 2.83019%;
    min-height: 1px;
    width: 82.86164%;
  }
}

+on-tablet-down

Argument Description Default
$breakpoint The max-width to use a breakpoint. Value of $shelves‑tablet‑breakpoint
$columns The number of columns in the grid. Value of $shelves‑tablet‑columns
$gutter The width of the gutter in the grid. Value of $shelves‑tablet‑gutter

Media query shortcut for targeting only mobile & tablet device sizes (widths below the tablet breakpoint). This also sets the global column and gutter contexts to the tablet settings.

@include on-tablet-down {
  article {
    // $total is set to $shelves-tablet-columns
    // $gutter is set to $shelves-tablet-gutter
    @include column(5);
  }
}
@media screen and (max-width: 799px) {
  article {
    position: relative;
    display: block;
    float: left;
    margin-left: 2.83019%;
    min-height: 1px;
    width: 82.86164%;
  }
}

+on-mobile

Argument Description Default
$breakpoint The max-width to use a breakpoint. Value of $shelves‑mobile‑breakpoint
$columns The number of columns in the grid. Value of $shelves‑mobile‑columns
$gutter The width of the gutter in the grid. Value of $shelves‑mobile‑gutter

Media query shortcut for targeting only mobile device sizes (widths below the mobile breakpoint). This also sets the global column and gutter contexts to the mobile settings.

@include on-mobile {
  article {
    // $total is set to $shelves-mobile-columns
    // $gutter is set to $shelves-mobile-gutter
    @include column(3);
  }
}
@media screen and (max-width: 479px) {
  article {
    position: relative;
    display: block;
    float: left;
    margin-left: 4.48113%;
    min-height: 1px;
    width: 73.87972%;
  }
}

+min-screen

Argument Description Default
$min‑width The min-width to use a breakpoint.

Media query shortcut for min-width breakpoints.

@include min-screen(480px) {
  article {
    color: red;
  }
}
@media screen and (min-width: 480px) {
  article {
    color: red;
  }
}

+max-screen

Argument Description Default
$max‑width The max-width to use a breakpoint.

Media query shortcut for max-width breakpoints.

@include max-screen(480px) {
  article {
    color: red;
  }
}
@media screen and (max-width: 480px) {
  article {
    color: red;
  }
}

+screen

Argument Description Default
$min‑width The min-width to use a breakpoint. null
$max‑width The max-width to use a breakpoint. null

Media query shortcut for min-width & max-width breakpoints.

@include screen(480px, 640px) {
  article {
    color: red;
  }
}
@media screen and (min-width: 480px) and (max-width: 640px) {
  article {
    color: red;
  }
}

Best Practices

Start with a Base

Even if you're going with a semantic approach, use the responsive base and a .row class to reduce duplication.

@include shelves-responsive-base;

// Optional:
// @include shelves-visibility-helpers;

.row {
  @include row;

  .row {
    @include reset-row;
  }
}
@media screen and (max-width: 400px) {
  @-ms-viewport {
    width: 320px;
  }
}

img {
  max-width: 100%;
  height: auto;
}

.row {
  margin-right: auto;
  margin-left: auto;
  padding-right: 20px;
  padding-left: 20px;
  max-width: 1060px;
}

.row:before, .row:after {
  display: table;
  content: " ";
}

.row:after {
  clear: both;
}

.row .row {
  margin-right: 0;
  margin-left: 0;
  padding-right: 0;
  padding-left: 0;
  max-width: none;
}

Mobile First

Build your grid from mobile up using the built-in Media Query Mixins:

// article and aside default to full width block-level elements

@include on-tablet-up {
  // Now add columns for tablet and desktop devices.
  article,
  aside {
    @include column-base;
  }

  article {
    @include column-width(3);
  }

  aside {
    @include column-width(1);
    @include column-gutter;
  }
}

@include on-desktop {
  // For desktops, add a little spacing between the columns
  article {
    @include column-width(8);
    @include suffix-column(1);
  }

  aside {
    @include column-width(3);
    @include column-gutter;
  }
}
@media screen and (min-width: 480px) {
  article,
  aside {
    display: block;
    float: left;
    min-height: 1px;
    position: relative;
    *margin-right: -1px;
  }

  article {
    width: 48.58491%;
  }

  aside {
    width: 14.30818%;
    margin-left: 2.83019%;
  }
}

@media screen and (min-width: 800px) {
  article {
    width: 66.03774%;
    padding-right: 8.49057%;
  }

  aside {
    width: 23.58491%;
    margin-left: 1.88679%;
  }
}

Use Placeholders

Heavy use of the @extend feature from Sass will reduce duplication in the generated CSS. Be aware of the limitations when used within @media directives.

%column-base {
  @include column-base;
}

// In this example only one element needs %column-gutter. But in a more
// complicated use-case using a placeholder will reduce duplication
// in the same way %column-base does.
%column-gutter {
  @include column-gutter;
}

article {
  @extend %column-base;
  @include column-width(9);

  @include with-parent-column(9) {
    h2 {
      @extend %column-base;
      @include column-width(6);
    }

    img {
      @extend %column-base;
      @include column-width(3);
      // use @include here because the context changes
      @include column-gutter;
    }
  }
}

aside {
  @extend %column-base;
  @extend %column-gutter;
  @include column-width(3);
}
article,
article h2,
article img,
aside {
  position: relative;
  display: block;
  float: left;
  min-height: 1px;
}

aside {
  margin-left: 1.88679%;
}

article {
  width: 74.5283%;
}

article h2 {
  width: 65.82278%;
}

article img {
  margin-left: 2.53165%;
  width: 31.64557%;
}

aside {
  width: 23.58491%;
}

Putting it All Together

Here's a complete example:

@include shelves-responsive-base;

.row {
  @include row;

  .row {
    @include reset-row;
  }
}

@include on-tablet-up {
  %tablet-column-base {
    @include column-base;
  }

  %tablet-column-gutter {
    @include column-gutter;
  }

  article {
    @extend %tablet-column-base;
    @include column-width(3);
  }

  aside {
    @extend %tablet-column-base;
    @extend %tablet-column-gutter;
    @include column-width(1);
  }
}

@include on-desktop {
  %desktop-column-base {
    @include column-base;
  }

  %desktop-column-gutter {
    @include column-gutter;
  }

  article {
    @include column-width(8);
    @include suffix-column(1);

    @include with-parent-column(8) {
      h2 {
        @extend %desktop-column-base;
        @include column-width(6);
      }

      img {
        @extend %desktop-column-base;
        @include column-width(2);
        @include column-gutter;
      }
    }
  }

  aside {
    @extend %desktop-column-gutter;
    @include column-width(3);
  }
}
@media screen and (max-width: 400px) {
  @-ms-viewport {
    width: 320px;
  }
}

img {
  max-width: 100%;
  height: auto;
}

.row {
  margin-right: auto;
  margin-left: auto;
  padding-right: 20px;
  padding-left: 20px;
  max-width: 1060px;
}

.row:before, .row:after {
  display: table;
  content: " ";
}

.row:after {
  clear: both;
}

.row .row {
  margin-right: 0;
  margin-left: 0;
  padding-right: 0;
  padding-left: 0;
  max-width: none;
}

@media screen and (min-width: 480px) {
  article,
  aside {
    position: relative;
    display: block;
    float: left;
    min-height: 1px;
  }

  aside {
    margin-left: 2.83019%;
  }

  article {
    width: 48.58491%;
  }

  aside {
    width: 14.30818%;
  }
}

@media screen and (min-width: 800px) {
  article h2,
  article img {
    position: relative;
    display: block;
    float: left;
    min-height: 1px;
  }

  aside {
    margin-left: 1.88679%;
  }

  article {
    width: 66.03774%;
    padding-right: 8.49057%;
  }

  article h2 {
    width: 74.28571%;
  }

  article img {
    margin-left: 2.85714%;
    width: 22.85714%;
  }

  aside {
    width: 23.58491%;
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
1
2
3
4
5
6
1
2
3
4