groot-sass

Groot

The root of all projects.

Groot is a class-based declarative CSS Grid system, originally derived from the amazing work Nicolas Gallagher produced with Griddle. I've been using Griddle for many years professionally and whilst I love the overall package, its not perfect and could do with a upgrade. I've started Groot with the intention of being that.

Groot prides itself on the following:

• Flexibility: Complete control to fit it into your own workflow or framework.
• Modular: Defaults to a BEM structured Grid System and keeps the Single Responsibility Principle in mind at all times.
• Configurable: Ability to change any class names, gutter sizes or alignment declarations to your hearts desire. Prefer SMACSS or ? Don't sweat it.
• Lightweight: With its opt-in columns, don't worry about bloated code, Groot will only create the code you need for your project. You're looking at around 4KB minified and gzipped
• Declarative: Opt-in, breakpoint specific classes for column sizings mean you're in control. Gone are the days of all sections/page conforming to the same Mobile/Tablet/Desktop sizes.

Installation

Groot is available through a number of package managers, including:

npm install --save-dev groot-sass
bower install --save groot-sass

Alternatively, you could always download/clone this repo and use it in your own way.

Usage

Groot is pretty easy to get to grips with. Once you've imported to the Groot system, use the groot mixin provided to build out the grids you need.

@import "groot";
@include groot($columns, $extension);

It takes two parameters:

• $columns: A space-separated list of integers, each of which results in the build of that particular grid.
• $suffix: The suffix for the class. This is optional and is intended when you're setting up a Groot instance within a Media Query.

Configuration

While Groot may have defaults for the configuration, you still have a lot of freedom in how you'd like to setup your version.

Each of the following variables should be declared above the import of Groot.

For example:

 
// Override default config here 
 
@import "groot";
 
// Include mixin here 

Available options and defaults:

Avaiable confirgurations can be seen by visiting the _variables.scss file. Here's a list for your convenience:

// Core 
$gr-grid: "grid" !default;                           // Main grid container which holds all elements 
$gr-item: "grid__item" !default;                     // Individual grid item/cell/unit/whatever you want to call it. 
$gr-item-unit: "grid__item" !default;                // The class chained onto the same element as above which controls the sizing. 
 
// Modifiers 
$gr-grid-spaced: "grid--spaced" !default;            // Increase gutter size 
$gr-grid-compact: "grid--compact" !default;          // Remove all gutters 
$gr-grid-reversed: "grid--reversed" !default;        // Reverse direction of the grid. i.e. direction: rtl; 
$gr-grid-centered: "grid--centered" !default;        // Centers the entire Grid, which grid items will inherit. 
$gr-item-centered: "grid__item--centered" !default;  // Center an individual item, rather than all items. 
 
// Sizing 
$gr-gutter: 1em !default;                            // The size between each grid item. Can use any CSS unit of measurement. 
 
// Grid Alignment 
$gr-grid-direction: inherit !default;                // Initial direction of the $gr-grid 
$gr-grid-align-x: inherit !default;                  // Initial horizontal alignment of the $gr-grid. 
 
// Item Alignment 
$gr-item-direction: inherit !default;                // Initial direction of the $gr-item 
$gr-item-align-x: inherit !default;                  // Initial horizontal alignment of the $gr-item 
$gr-item-align-y: top !default;                      // Initial vertical alignment of the $gr-item 

Modifiers

Here's a list of the modifier's are their default class names. You can see examples of all these by going to the examples section of the README.

.grid--spaced

Add this to the containing grid and the gutters width will be doubled.

.grid--compact

Add this to the containing gird and the gutters will be removed.

.grid--reversed

Add this to the container grid to reverse direction of it.

.grid--centered

Add this to the containing grid centers it and anything within (through CSS inheritance).

.grid__item--centered

Adding this to a grid item centers only it, rather than all items.

Examples

An accompanying website has been created to demonstrate Groot's capabilities and how to correctly use it.

• Basic Usage: How to create a basic grid without any modifications of any kind and using the system defaults.
• Nesting: Gridception yo. Example grid with other grid's inside of it.
• Modifiers: An example of each of the default modifiers, as described above.
• Reversed: An example of each of the default modifiers, as described above.
• IE8: An example of Groot without media query classes (for IE8 and below - read below for more information)

Compatability

Groot has been tried and tested within the latest browsers, but also works great for those older versions of IE that you may still need to support (I feel your struggle). Here's a full list of the browser/device combinations that Groot has been verified in. If you feel theres a problem with any of these, please open an issue and we'll try to resolve it together.

Mac/Windows:

• Chrome
• Firefox
• Safari
• Opera
• Edge
• IE8+ !!

Mobile:

• iOS7+
• Android 4.3+
• Windows Phone

!! Whilst Groot does support IE8, there are caveats. IE8 doesn't support media queries and therefore you'll need to make sure you use something like respond.js. However, I'd recommend if you need IE8 support that you give Jake Archibold's Media Query Mixin a read. Its great! Here's an example of Groot working in IE8 without any media queries.

Roadmap

Here's a quick roadmap on where I'd like to take Groot in the coming months.

• Companion website: To better show Groot off and make it look like I made something.
• Screencasts: Showing detailed examples on how you can use Groot in your projects.
• LESS/Stylus support: Because not everyone uses Sass, right?

Credits

With any project, theres always special thanks and recognition to be given:

• Griddle: The inspriation for Groot.
• Mixd: Who introduced me to Griddle in the first place. If – like us – you work with WordPress then you may be interested in our Open Source project called wp-deploy; a capistrano-powered deployment tool for WordPress.

License

MIT License (MIT)

Copyright (c) 2015 Luke Whitehouse, https://github.com/lukewhitehouse/groot

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.