Quick Start

Robin Pokorný edited this page Nov 18, 2015 · 15 revisions


Install with Bower

Use Bower for easy install and version management:

$ bower install emerald --save

Manual download

Download ZIP of the latest version with compiled and minified CSS, LESS source files, and JavaScript included. Unzip it somewhere in your project folder (lib folder could be a good idea).


What is included

Get familiar with the Emerald folder structure. Depending on your needs you will either use CSS or LESS files.

├── css/
│   └── emerald.css
├── js/
│   └── emerald.js
└── less/
    ├── ...
    ├── emerald.less
    └── variables.less

Without Compilation

Using directly Emerald's CSS is a quicker and easier way. Just include provided emerald.css file to you page. Here I suppose you have downloaded Emerald inside lib folder, make sure you replace it with the correct path.

<!doctype html>
    <link rel="stylesheet" href="lib/emerald/css/emerald.css">

With Compilation

When you include source LESS files and then compile them, you will have access to mixins and variables. This way you can change number of columns, responsive breakpoints, and other behaviour.

Import emerald inside your LESS file. Here I suppose you have a working LESS setup, and you have downloaded Emerald inside lib folder, make sure you replace it with the correct path.

@import "lib/emerald/less/emerald.less";

All other files are linked from this main style with correct folder.

Tip: All Emerald files have inline comments which explain how to use mixins and variables. Do not hesitate to explore the source code.

Columns concept

The most interesting and unique thing about Emerald is the way it works with its columns. Namely that column count varies across devices, that gutters are the same width as columns, and that columns are—in certain meaning—global.


In the following table you can see how grid work on different devices. These three are default, of course you can change any number in there if you decide to modify the system.

Device Mobile Tablet Desktop
Screen width < 768px 768px - 1020px > 1020px
Column count 8 16 25
Column width 6vw 20px
Gutter width
Postfix --palm blank (--lap) --desk

This means columns add up when resolution increases, see the next image or try it yourself:


Coding layout

Add the following basic code with two blocks. All parts are explained below.

<div class="wrapper">
    <div class="grid"><!--
        --><div class="grid__item">…</div><!--
        --><div class="grid__item e-4--palm e-8 e-12--desk">…</div><!--

### Items

Any content can be wrapped in a .grid__item element. These elements can span across certain amount of columns on different devices.

By default an item is full-width. To set its size add a class in the following format:

Emerald specific prefix Size Device postfix
.e- an integer, e.g. 4 --palm, --desk, or blank

These size classes apply in a mobile-first manner. An item with class .e-2--palm will span across 2 columns on mobile, tablet, and desktop (on each device 2 columns represent different portion of the screen) unless changed by a class for a “bigger” device.


Items are organised in .grid elements. It is required that .grid__item's (immediate) parent is a .grid element.


The wrapping class .wrapper ensures that the content of the page is centered. Every .grid element has to have exactly one .wrapper ancestor.


Class crossing

Never add your own classes to .grid or .grid__item elements, e.g. for text centering. Always nest a block inside and style it.

Conversely, never use .grid or .grid__item specific modifier elsewhere, e.g. .grid--right on a paragraph. These classes may have a side-effect.


Emerald takes advantage of inline-block ordering in the browsers. This means items behave as if they are word on a line.

Because of this there MUST NOT be whitespace between any two items.

There are several methods how to achieve that (see related article Fighting the Space Between Inline Block Elements at CSS Tricks), in the docs and examples we will remove the spaces by comments.

### E-zero classes

Classes .e-0--palm, .e-0, and .e-0--desk completely hide a column on a specific device. Such column then neither affects any other column nor occupies a space.

Please note that these classes do not follow the mobile-first manner, e.g. .e-0 will be visible on desktop by default. However, they can be combined, .e-0.e-0--desk would make a column hidden on both tablet and desktop.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.