My workflow with the Stylus and Flexbox grid system

Yes, this is an article about another css grid system, but it’s not only theory. This is also an introduction to some cool tools which you can use in your daily workflow. Please take a moment and read further. I think it’s worth it.

When you think about css grid system you probably think about Bootstrap or Foundation or hundreds of other grid systems. I’m sure that all of these tools are really great.

So why have I built another grid system? Let’s see…

  1. I needed a very light Stylus library
  2. I needed only a plug-in-able grid system without any other UI elements
  3. I needed a Flexbox grid
  4. I needed grid classes for prototyping but also Stylus functions to build custom and semantic grids.
  5. I needed a grid which is fully configurable — columns amount, gutters, flexbox properties, breakpoints etc.

If you think this is something which might be interesting, you should read further. You’ll learn how to use my grid, but also you’ll be able to build yours based on my work which is totally open sourced and MIT licensed. Also you’ll see how to use my grid system with tools such as Grunt, React and even with Meteor. You can use my Grunt and React boilerplates and also Meteor package, which you’ll read about later. For now, let’s see what’s going to be covered here and what not.

What we’ll cover here:

  1. Why Stylus and Flexbox?
  2. sGrid and Npm package walkthrough
  3. How to use it with: Meteor, React and Grunt
  4. Layout examples built upon sGrid
  5. When to use sGrid and when not to

What we’ll not cover here:

  1. Stylus tutorial
  2. Flexbox tutorial

Why Stylus and Flexbox?

I always wonder why Stylus is such an underrated css preprocessor. It is a JavaScript based tool like Less and, in my opinion, it has much better API. It is also very nicely suited to every JavaScript workflow. I’ll talk more about it later. I really love how you can build functions or mixins with it. You can write with all those curly brackets and semicolons, but you can also omit them. All is good. This flexibility is really cool, but what is most important is that this code looks like normal JavaScript (or other programming language) code. Here’s a very simple example. Just look at this function. Isn’t it clear?

compare(a, b)
if a > b
else if a < b

This is much better than in Scss or Less.

Why Flexbox? This is the harder part. Flexbox is something new. Although it has been here for a couple of years, we still have some problems with it even on modern browsers. So, I don’t want to tell you that you should use it everywhere. You might use it if you are sure that you can. I will tell you when not to use Flexbox or this grid later in the article.
So, what are the pros of Flexbox? First of all, it solves many css problems like vertical aligning, some layout problems like sticky footers or Holy Grail Layout. You can also write better looking forms with it and many more.
sGrid uses Flexbox with the native css calc() function. These features are really useful in building grids. It is much less css code and better control.

Read more about Flexbox here:

sGrid and Npm package walkthrough

Let’s see where we can find some code. First of all, there is a separate sGrid website with documentation here: but all grid functionality is in the Npm package which you can find here:

All you need to know is that there are three Stylus files. One with core functions, one with settings and an optional one which will generate ready to use css classes (like those known from Bootstrap).

All you need is to use the Npm package and just like with all other Stylus libraries you can import Stylus files:

@import 's-grid-settings'
@import 's-grid-functions'
@import 's-grid-classes' // optional

Of course there is the option to overwrite the settings and even functions in your main .styl file.

sGrid is all about two main functions: ‘grid()’ and ‘cell()’ which has some Flexbox attributes. There are also ready to use helper classes like, for example: ‘s-grid-cell-sm-12’ or ‘s-grid-cell-md-10’.

You will find detailed documentation about sGrid functions and helper classes on the website: so I won’t copy it here.

Instead, I will show you a very simple example. Let’s say we want a container which is maximum 1200px width and is centered. Inside we want 2 columns and all should be responsive. In our .styl file we could write something like:

cell(1, 2)

and in html:

<div class='container'>
<div class='column'>lorem ipsum 1</div>
<div class='column'>lorem ipsum 2</div>

Of course you can use media queries here and, for example, ‘stack()’ function to stack the cells when we use the website on mobile devices.

Also here is a codepen with a simple grid example. You can play with it live:

How to use it with: Meteor, React and Grunt

I use this grid system in projects which are based on Meteor, React or are just simple html projects based on Grunt workflow. This is why I have prepared some ready to use starter kits or boilerplates. This is really helpful because you have a configured environment with sGrid and many tools like Autoprefixer, which is really necessary here because of Flexbox and all vendor prefixes.

So if you want to start your new project with sGrid and Meteor, just add the package:

$ meteor add juliancwirko:s-grid

More info:

If you want to run your React project with Webpack and sGrid just use the boilerplate:

$ git clone

More info:

Or maybe you just want a simple html project with some Grunt tasks like cssmin, uglify, concat, assemble, livereload, then use Grunt boilerplate:

$ git clone

More info:

You will find detailed documentation on these webpages. All projects are open sourced and MIT licensed so please try to use them and I encourage you to help me with these projects. You can always contact me on Twitter or e-mail. I would be very grateful for it.

Layout examples built upon sGrid

We will take a closer look at the two websites. One is a simple Meteor app built with sGrid and the second one is a main sGrid website built with a Grunt starter kit. Why these two? Because the first is built using sGrid helper classes (of course not only) and the second is built using only sGrid functions. Both have open sourced code so you can go and see it on GitHub. Here are the links:

I won’t lead you through all files of these websites. If you want to check how it works, just clone it and run it. In the case of Meteor just run ‘meteor’ command in the project folder and with the website you can clone it and run ‘grunt’ command. Of course more information about these workflows are linked above.

We will take a closer look at the .styl files.

First, let’s open one of the Meteor project templates which uses sGrid helper classes: promo.html. You can see here how it is used and then let’s open the main style.styl file of the same app. As you can see, we’ve just imported all three sGrid .styl files including the file with classes which we’ve used in the promo template. Promo template uses some responsive sGrid classes like ‘s-grid-cell-sm-12 s-grid-cell-md-10’ I am sure that you know it from, for example, Bootstrap grid. This is the same. We have 12 columns on the small screen and 10 on the bigger one. You can copy and overwrite the config file from s-grid-settings.styl file.

You can find the website here:

The second website is the sGrid homepage. Just take a look at its Stylus code: app.styl. As you can see, in many places we use functions like grid(), cell(), center(), stack() they are all from sGrid functions styl file. Here we don’t use the ‘s-grid-classes.styl’ file. It is only imported because of the grid demos purposes. Also when you take a look at the html: index.html you’ll see that there aren’t any helper classes used and the sGrid is still working. This is the way I like to work with such grids.

Of course you can find the website here:

I encourage you to clone these projects and play with it. This is the best way to learn and to build upon it.

When to use sGrid and when not to

sGrid is a very useful tool, but sometimes you really don’t want to use it. This is especially when you want to support an older browser. That’s because of Flexbox compatibility which is quite good now, but some browsers still have problems with it.

Use it when:

  • You need Flexbox grid and you work with Stylus
  • You work with Meteor or other JS platforms and need only a grid system
  • You don’t need to support older browsers
  • You want to build a mobile hybrid app
  • You want a very light grid system without other UI elements

Do not use it when:

  • You need to support older IE browsers like IE 10 and below
  • You want to build some really complicated grid layouts and you need to support IE 11 browser

Let’s see if ‘Can I Use’ Flexbox:
Hmmm, yes I can, but… oops! We have some

And this is really a very important resource to read before you start working with Flexbox and sGrid. You should definitely read it. There are some Flexbox bugs in IE 11 which has workarounds and are described in this GitHub repo. I hope that Edge browser is free of these bugs.

sGrid summary

Here you have a simple and functional grid system based on Flexbox which you can use with helper classes or with Stylus functions. It has flexible settings to overwrite, and it is a very small and light library.

You can use it as a standalone Npm package, with a ready to use Grunt project scaffold, with a Meteor project or even with React boilerplate.

Let me know in the comments if you have any ideas on how to improve the grid or how to improve particular workflows with boilerplates like React and Grunt.

If you want to try other grid systems, I can recommend awesome grids. Take a look at:

  • Jeet — If you don’t want to use Flexbox and you like how sGrid is built.
  • Lost — Great grid. You can use it with PostCSS
  • Zurb Foundation Grid — Foundation 6 Grid will be so cool! You definitely need to check it out. (Scss)

Also check out “sGrid — Working with Flexible Box layouts” article and Introducing sGrid: A Stylus-based Flexbox Grid System.