Msdotcom/WinJS Grid Framework

A CSS grid framework built on SASS to provide an automatic responsive grid for web developers with flexibility for manual control when needed. This grid is a float and padding-based grid, meaning that it works by using floats to create rows and padding to create the gutters between columns instead of margin.

This framework is built based off of config values so any number of columns, gutter sizes, column breakdowns, and breakpoints can be configured and built with ease.

Supports column layouts of 1, 2, 3, 4, 5, 6, 8, 12, and 24 by default.

Demo

http://msdotcom.azurewebsites.net/Grid

Install

With Bower

bower install winjs-grid

With Grunt

First you must have installed Node.js. Then install Grunt CLI as an admin user:

npm install -g grunt-cli

Then in the folder of the repository install the required npm packages:

cd grid
npm install

Or just recompile the Sass files:

grunt

Built-in server

You can launch a static server which watches for changed Sass files and automatically recompiles the changed files:

grunt server

With this server you can access the demo page at this URL: http://localhost:3000/

With the SASS command line

sass --watch --sourcemap --style compressed css:css

Usage

A grid is a container for rows and rows are containers for columns. A grid should never have another grid nested anywhere inside it, only one grid is needed for a section that is using the grid framework.

Class breakdown

The grid and row class names can be prefixed with any text you'd like, we default to "ms" but you can use whatever you'd like by setting the SASS grid-prefix variable in the config file. See below.

Grid - .ms-grid

Row - .ms-row

Columns: Auto columns - .col-1-24 where the numbers mean # of columns to span and total # of columns, respectively. Manual columns - .l-col-1-24 same as above but with a viewport/breakpoint size prefix.

Please see the "automagic" and manual column spanning sections below for details on what and how values are supported for the column span number.

###SASS configuration variables Through the use of the variables in the _config.scss file, you can control:

Number of columns
The way columns will breakdown by breakpoint (i.e. if a 24 column should become 12 based at some point)
Maximum width of the grid
Prefixing of the grid and row classes
Fixed column margin mode's fixed margins (standard, small, large)
Mixed langauge support
Breakpoint values for the 5 built in breakpoints/viewports
Prefixing of the viewport specific classes (manual colspans and offsets)
Toggle including of specific grid features, if not being used, can shave down final build size
Toggle the ability for the grid features to be specifically tied to the way you configure your columns and column breakdowns, the default is false, which means all features are tied to their column number's direct percentages across all breakpoints. s-col-24-push-4 and l-col-24-push-4 will both push by the same percentage, 4/24.

$max-grid-width: 1600px !default;
$fixed-standard: 2px !default;
$fixed-small-margin: 2px !default; //4px fixed margin for start of small fixed option which steps up, 4px, 12px, 24px
$fixed-large-margin: 4px !default; //8px fixed margin for start of large fixed option which steps up, 8px, 24px, 48px
$grid-prefix: "ms-" !default;
$dirMixed: false !default; //Toggle for having mixed langauge support


//Flags to include specific features of the grid, can be toggled to fine tune your final build size.
$includePushPull: true !default;
$includeOffsets: true !default;
$includeVisibility: true !default;
$includeGridHelpers: true !default;
$includeRowHelpers: true !default;
$includeManualColspans: true !default;


//This value toggles if you want the manual column span, push/pull, and offset classes to honor the column breakdowns
//specified in the $columns variable below. This would make these features classes alter their behavior to match the 
//widths of columns as decided by their values below. ex) a s-col-1-4 would be 50% wide vs the normal 25% wide
$honorAutoColumnBreakdown: false !default; 
//Columns supported AND their associated "automatic" rwd column breakdown
//Can be any amount - 1 column doesn't need to be specfied
//Format for key/value pair - columnCount: (vp1col, vp2col, vp3col, vp4col, vp5col)
//The objects in this map can be decresed if not being used to fine tune your final build size.
$columns: (2: (1, 1, 2, 2, 2), 3: (1, 3, 3, 3, 3), 4: (1, 2, 4, 4, 4),
5: (1, 1, 5, 5, 5), 6: (1, 2, 3, 6, 6), 8: (2, 2, 4, 8, 8), 
12: (2, 4, 4, 12, 12), 24: (6, 12, 24, 24, 24));



//Grid breakpoints, different viewport sizes and list for mixin use
$vp1: 320px;
$vp2: 540px;
$vp3: 768px;
$vp4: 1084px;
$vp5: 1400px;
$vp-list: ($vp1, $vp2, $vp3, $vp4, $vp5);



//Different prefixes for each viewport and list for mixin use
$vp1prefix: xs;
$vp2prefix: s;
$vp3prefix: m;
$vp4prefix: l;
$vp5prefix: xl;
$vp-prefix-list: ($vp1prefix, $vp2prefix, $vp3prefix, $vp4prefix, $vp5prefix);

Grid Features

"Automagic" responsive breakdown

Built into the grid is an opinated take on how the different column layouts should reflow and breakdown across the 5 breakpoints. This works nicely for those that want to get up and running quickly, need their content to look great across many screens, and don't need the granualar control over the breakdown of columns for each breakpoint.

In this "automagic" mode, only certain column spanning values are supported out of the box. For example, if you need a column spanning 7 columns in a 24 column layout, you'll need to use the manual class overrides described below.

Column spanning options that are supported "automagically", these will reflow and respond across the different breakpoints without any manual classes:

| Columns | Spans | |:-------:|:--------------:| | 1 | 1 | | 2 | 1, 2 | | 3 | 1, 2, 3 | | 4 | 1, 2, 3, 4 | | 5 | 1, 2, 3, 4, 5 | | 6 | 1, 2 ,3 ,4, 6 | | 8 | 1, 2, 4, 6, 8 | | 12 | 1, 2, 4, 12 | | 24 | 1, 6, 12, 24 |

Example row:

<section class="ms-row">
    <div class="col-3-4 ">
    </div>
    <div class="col-1-4 ">
    </div>
</section>

Column breakdown across each breakpoint:

| Columns | < 320px (mf) | > 320px (vp1) XS | > 540px (vp2) S | > 768px (vp3) M | > 1084px (vp4) L | > 1400px (vp5) XL | |:-------:|:------------:|:-------------:|:-------------:|:-------------:|:-------------:|:--------------:| | 1 | 1 | 1 | 1 | 1 | 1 | 1 | | 2 | 1 | 1 | 1 | 2 | 2 | 2 | | 3 | 1 | 1 | 3 | 3 | 3 | 3 | | 4 | 1 | 1 | 2 | 4 | 4 | 4 | | 5 | 1 | 1 | 1 | 5 | 5 | 5 | | 6 | 1 | 1 | 2 | 3 | 6 | 6 | | 8 | 2 | 2 | 2 | 4 | 8 | 8 | | 12 | 2 | 2 | 4 | 4 | 12 | 12 | | 24 | 6 | 6 | 12 | 24 | 24 | 24 |

Manual column spanning

Manual column span class overrides are supported for all column counts and all breakpoints. Here is the pattern for the classes:

viewport - col - # of columns to span - total # of columns

Examples:

s-col-3-24 - 12.5% of the viewport - At the small(viewport 2) breakpoint and above, this column will span 3 columns of the 24 columns in the row.

l-col-14-24 - 58.3333333333% of the viewport - At the large(viewport 4) breakpoint and above, this column will span 14 columns of the 24 columns in the row.

Fluid vs. fixed gutter options

The grid can support fluid, fixed, and zero/no gutter options, all of which is configurable. By default the grid uses fluid gutters. If you want to use fixed gutters, you will add one of three helper classes: fixed, fixed-small, or fixed-large. Zero or no gutter uses the helper class zero-margin.

To apply these different gutter options, you place the corresponding helper class on the grid element or an individual row. Place on the grid if you want it to go across that entire grid. Place on an individual row if you'd like to scope the behavior to only that row.

Fluid - this is the default behavior.

fixed - stays at one value across all breakpoints, default is 4px.

fixed-small - starts at 4px, jumps to 12px at viewport 2, and to 24px at viewport 3.

fixed-large - starts at 8px, jumps to 24px at viewport 2, and to 48px at viewport 3.

zero-margin - removes all gutters between columns.

Page margins

The grid supports two flavors of page margins. None or full width and an option with margin.

The default grid's page margins start at 12px, jump to 24px at vp2, 48px at vp3, and 5% at vp4.

The full class added on the grid element will enabled the no margin experience.

Offsets

Using these classes will offset a column by a specified amount.

Here is the pattern for the classes: viewport - col - total # of columns - offset - # of columns to offset

Example: l-col-8-offset-2 - This will offset the column by 2 column widths for an 8 column row above the large(viewport 4) breakpoint.

Column ordering (push/pull)

Using these classes will allow you to change the built-in column ordering .

Here is the pattern for the class

Grid

Install / Use

README