Creating Grids
In Singularity, Grids are an expression of pieces of a whole. Grids are a combination of the $grids variable and the $gutters variable. Both $grids and $gutters should be expressed as unitless numbers; they represent relationships to each other. Setting $grids and $gutters sets a global context for either variable respectively, allowing you to use the grid-span mixin without passing them in.
You can set $grids either as a single number to create that number of equal sized columns (which we will refer to as symmetric grids), or a list of numbers (including decimals) to describe the relational size of one column to another (which we will refer to as asymmetric grids). Gutters, on the other hand, can only be set to a single number (again, decimals included). The size for gutters is in relation to a column of size 1 in your grid; for symmetric grids, each column is considered a size 1 column, for asymmetric grids it's based on a calculated size 1 column, even if you do not have a column sized 1.
As an example to undersand the $grids and $gutters, let's take a look at a standard 12 column symmetric grid similar to the 12 column 960 grid. In the 960 grid, each column is 60px wide with 10px gutter on each side, giving it a total of 20px gutter. If we write that as a ratio, we've got 60px:20px, which can be reduced to a 3:1 ratio. So, the way we can write this using Singularity is as follows:
// Singularity 1.0 Syntax
$grids: 12;
$gutters: 1/3;
// Singularity 1.2+ Syntax
@include add-grid(12);
@include add-gutter(1/3);This creates a beautiful grid for us that looks like this:
The slight difference between 960's grid and Singularity's grid is that Singularity doesn't make assumptions about your container, and the gutters on the far edges actually reduce the total container as opposed to being true gutters.
Now, imagine we wanted a triptych layout using that same 12 columns. We can imagine we'd want the two outer pieces to be the same size, and have the inner piece be larger. Now, instead of remembering what the span for each piece is of the triptych is, we can build a grid that has that built in! We can do it more effectively by using asymmetric grids! An example of an asymmetric grid for this could look like this:
// Singularity 1.0 Syntax
$grids: 2 8 2;
$gutters: 1/3;
// Singularity 1.2+ Syntax
@include add-grid(2 8 2);
@include add-gutter(1/3);
Responsive Grids are an advanced way to automatically change your global grid and gutter context. It is important to keep in mind that, when using Responsive Grids, Singularity is not rewriting your existing grid-span calls, but rather changing your global contexts allowing you to change them at will, thus allowing you to use grid-span as normal and getting the correct shared context. Responsive Grids work thanks to some advanced features in Breakpoint, so you need to be using Breakpoint (or a mixin built off of Breakpoint, like its alternative Respond-to syntax) for Responsive Grids to work.
By default, we assume that you are following best practices and are building Mobile First. If, however, you aren't, you can set $mobile-first: false; to switch the Responsive Grid assumptions. Be aware that if you are not building Mobile First, you will probably want to change Breakpoint's $breakpoint-default-feature to max-width; Singularity will not make that switch for you automatically. If you're building Mobile First, you start with your smallest grid and gutter first, then use the add-grid() or add-gutter() functions to add either at a given size. The size will either be correspond to a min-width or max-width media query depending on if you are building Mobile First or not. The context will change when inside a min-width or max-width media query that matches. If you are within an Or Query, if any of the queries match, Singularity considers that a match and the context will change. It's easier to see an example, so here is a Mobile First one!
// Singularity 1.0 Syntax
$grids: 3;
$grids: add-grid(6 at 500px);
$grids: add-grid(12 at 700px);
$grids: add-grid(2 8 2 at 900px);
$grids: add-grid(1 3 5 7 9 at 1100px);
$gutters: 1/3;
$gutters: add-gutter(.25 at 900px);
// Singularity 1.2+ Syntax
@include add-grid(3);
@include add-grid(6 at 500px);
@include add-grid(12 at 700px);
@include add-grid(2 8 2 at 900px);
@include add-grid(1 3 5 7 9 at 1100px);
@include add-gutter(1/3);
@include add-gutter(.25 at 900px);In the above example, there are 5 grid contexts, a combination of symmetric and asymmetric grids, and 2 gutter contexts. We start with the basic grid and gutter contexts, and then at min-width: 500px the grid context changes to a 6 column symmetric grid but the gutter context stays the same. At min-width: 700px the grid context again changes, this time to a 12 column symmetric grid, again with the gutter context staying the same. At min-width: 900px both the grid and gutter contexts change, to a 2 8 2 asymmetric grid and a .25 gutter respectively. At min-width: 1100px the grid context changes to a 1 3 5 7 9 asymmetric grid, with the gutter context staying at .25. The Desktop First version of the above would look like this, substituting out min-width with max-width.
// Singularity 1.0 Syntax
$mobile-first: false;
$grids: 1 3 5 7 9;
$grids: add-grid(2 8 2 at 1100px);
$grids: add-grid(12 at 900px);
$grids: add-grid(6 at 700px);
$grids: add-grid(3 at 500px);
$gutters: .25;
$gutters: add-gutter(1/3 at 900px);
// Singularity 1.2+ Syntax
@include sgs-change('mobile first', false);
@include add-grid(1 3 5 7 9);
@include add-grid(2 8 2 at 1100px);
@include add-grid(12 at 900px);
@include add-grid(6 at 700px);
@include add-grid(3 at 500px);
@include add-gutter(.25);
@include add-gutter(1/3 at 900px);Singularity's gutters, by default, are fluid and based on a column of size 1, and are set in the opposite direction of your writing direction (to the right for 'ltr' grids and to the left for 'rtl' grids). While this will work for most grids, sometimes a design calls for the gutter to be split on either side of a column or for the gutters to be a fixed width. By setting $gutter-styles, you can achieve this in Singularity.
$gutter-styles works in the same way as $grids and $gutters do; you can set a single option or a series of options by using the add-gutter-style() mixin. The default for $gutter-styles is 'opposite', which is assumed throughout Singularity; however, you can change it to 'split' for split gutters, 'fixed' for fixed width gutters, or 'split' 'fixed' for fixed width gutters whose width is evenly split on either side of the column.
In Singularity, the full width of a gutter is normally placed on the opposite side of your writing direction. If, however, you would like to split the gutter's full width evenly on either side of a column, you can do so by setting the following:
// Singularity 1.0 Syntax
$gutter-styles: 'split';
// Singularity 1.2+ Syntax
@include add-gutter-style('split');In Singularity, the default way gutters are defined is as a ratio to a column of size 1, creating fluid grids. There are times, however, when fixed width gutters would be preferred. There are two ways of defining fixed width gutters in Singularity: either by betting the gutter definition in a different unit than your grid definitions, or by setting the gutter style to fixed (which can be combined with 'split'):
// This will create a 5 column symmetric grid with fixed 1em gutters to one side of a column
// Singularity 1.0 Syntax
$grids: 5;
$gutters: 1em;
// Singularity 1.2+ Syntax
@include add-grid(5);
@include add-gutter(1em);// This will create a 3 column asymmetric grid with fixed 15px gutters to one side of a column
// Singularity 1.0 Syntax
$grids: 40px 80px 120px; // Will be calculated as ratios to each other in Singularity
$gutters: 15px;
$gutter-styles: 'fixed';
// Singularity 1.2+ Syntax
@include add-grid(40px 80px 120px);
@include add-gutter(15px);
@include sgs-change('gutter styles', 'fixed');// This will create a 6 column symmetric grid with fixed .5em gutters on either side of a column
// Singularity 1.0 Syntax
$grids: 6;
$gutters: 1em;
$gutter-styles: 'split';
// Singularity 1.2+ Syntax
@include add-grid(6);
@include add-gutter(1em);
@include sgs-change('gutter styles', 'split');// This will create a 4 column asymmetric grid with .75em gutters on either side of a column
// Singularity 1.0 Syntax
$grids: 2em 5em 5em 3em; // Will be calculated as ratios to each other in Singularity
$gutters: 1.5em;
$gutter-styles: 'split' 'fixed'
// Singularity 1.2+ Syntax
@include add-grid(2em 5em 5em 3em);
@include add-gutter(1.5em);
@include sgs-change('gutter styles', 'split' 'fixed');When using fixed gutter grids, padding is added instead of margins. As such, it is imperative that your are utilizing box-sizing: border-box.
Once you've created your grids, it's nice to be able to visualize them. Singularity comes with the background-grid mixin to allow you to do just that. It is a simple mixin you can apply to any element to have a visualization of your grid built out using SVGs. If you do not pass anything into it, it will build a visualization based off of your set grids and gutters. If you are utilizing Responsive Grids, it will create visualizations of your grid at your grids' breakpoints. If you would like more control over visualization gets built, you can pass in your own grid, gutter, or color (in that order) into the background-grid mixin. The default color for the grid is Chocolate. You can change this color by either passing a color, or changing the 'background grid color' setting.
// Be sure to enable debug mode for your grid visualization so show up:
@include sgs-change('debug', true);
.container {
@include background-grid($color: blue);
}IT IS IMPORTANT TO NOTE that if you are using Singularity < 1.6.0, CSS Gradients are used instead of SVG. CSS Gradients are not 100% reliable visualizations of your grid, so do not be concerned if your items do not line up to the visualization. If they are off by a little bit, assume that they are aligned correctly and your visualization is off. Webkit browsers, and especially Google Chrome, seem to be the worst with the gradients, whereas Firefox seems to be the best.