# Creating Grids

Sam Richard edited this page Feb 25, 2015 · 20 revisions

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.

## Symmetric Grids

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

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.

## Asymmetric Grids

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);

## Responsive Grids

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(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(.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(1/3 at 900px);```

## Gutter Styles

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.

### Split Gutters

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

### Fixed Gutters

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
```// 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 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 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 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`.

## Visualizing Your Grids

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);
}```

### Grid backgrounds may be inaccurate

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.

##### Clone this wiki locally
You can’t perform that action at this time.
Press h to open a hovercard with more details.