Spanning The Grid

Singularity is what we like to call a semantic grid system, meaning that instead of grid classes being generated that you then apply to your HTML, the grid is stored entirely within your CSS and applied directly to the element you want to use it on. This makes working with responsive grids very easy as you don't need to swap classes using JavaScript or combine lots of assumptions into a single class. It also allows you to build and use grids that are not tied to specific sizes, allowing you to make more compelling and future friendly designs. The key to all of this is the grid-span mixin.

Grid Span

The key to spanning your grid is to use the grid-span mixin. The two inputs that are needed are $span and $location referring to how many columns you want to span, and what column you would like to start your calculation at. This combination of number of columns you are spanning and where you are starting your calculation from is your grid span. For symmetric grids, $location will not necessarily determine the total width of your grid span, but it is very important for asymmetric grids as the width of your grid span will change depending where on the grid you are. That being said, it is also important to know how your chosen output style will use both $span and $location. Let's take a look at a few examples:

$grids: 1 2 3 4 5;
$gutters: 1/3;
$output: 'float';

// Span 1 column, starting at the 2nd column
.span-1-2 {
  @include grid-span(1, 2);
}

// Span 3 columns, starting at the 5th column
.span-3-5 {
  @include grid-span(3, 5);
}

Context Overrides

The Grid Span mixin also takes optional inputs to allow you to override the global contexts for grids, gutters, and output styles on an as-needed basis. The first optional parameter, $grid, overrides the global grid context, $gutter the global gutter context, and $output-style the global output style context. Some examples of overriding are presented below:

$grids: 1 2 3 4 5;
$gutters: 1/3;
$output: 'float';

// Overrides the global Grid context provided by $grids with a 12 column symmetric grid
.override-grid-symmetric {
  @include grid-span(1, 2, 12);
}

// Overrides the global Grid context provided by $grids with a 2 4 5 asymmetric grid
.override-grid-asymmetric {
  @include grid-span(1, 2, (2 4 5));
}

// Overrides the global Gutter context provided by $gutters with a .25 gutter
.override-gutter {
  @include grid-span(1, 2, $gutter: .25);
}

// Overrides the global Output Style context provided by $output the Isolation output style
.override-output-style {
  @include grid-span(1, 2, $output-style: 'isolation');
}

// Overrides the global Grid context provided by $grids with a 12 column symmetric grid, the global Gutter context by $gutters with a .25 gutter, and the global Output Style context provided by $output with the Isolation output style
.override-all-the-things {
  @include grid-span(1, 2, 12, .25, 'isolation');
}

Grid Span Options

Finally, some Output Styles may have additional options that need to be taken into consideration. See the Output Styles documentation to see if an output has additional options it supports that should be passed in. If one does, simply pass the needed options in to the Grid Span mixin using the $options variable.

Output Span

Output Styles may choose to optionally provide an output-specific span mixin to make working with their specific quirks easier. These mixins are all wrappers of grid-span with additional syntactical sugar and a fixed Output Style. Both of Singularity Core's Output Styles, Isolation and Float, provide output-specific span mixins to make using them easier.

Isolation Span

isolation-span is nearly identical to grid-span, with the exception that the third argument is $clear instead of $grid, allowing for easier control over the clear direction. $grid and $gutter are also available for you to pass in as in the normal grid-span.

Float Span

float-span is functionally identical to grid-span for asymmetric grids, but has some additions for symmetric grids. Because the common way to work with symmetric grids when using the Float output method is to walk along a row, and each column is the same width, when using float-span and a symmetric grid, $location is optional. Additionally, you can pass either 'last' or 'omega' in for $location in the call and float-span will make sure that item is the last in the row. You can also pass in either 'first' or 'alpha' to $location to force a new row to start.