Grace

Web Frontend Fundament

We at Me & Company are using this boilerplate project to set up our web projects. It unifies the structure of each project and simplifies the start of development.

Essentially, it provides the folder structure and some basic files for SASS and JavaScript. It has a builder included with various tasks, which add value to each project and improve the quality without any major effort. We implemented some features, at this stage especially for the work with SASS. It is adaptable for other frameworks, but can also be used as an independent HTML framework.

Installation

Download or clone into your project folder
Run npm install
As macOS user you need some extra steps for the images build process to work: Install Homebrew, then install libpng library with brew install libpng
Run gulp dev and you are ready to go

Features

1. HTML

There is a basic index.html file, where you can import template snippets via Gulp File Include e.g.:

    <html>

    @@include('./src/html/snippets/header.html');

    ...

    </html>

With gulp include the html files get build and gulp html minifies them into the dist folder.

2. SASS

Settings

We have variables for most attributes in CSS, which are individual for each project and design related.

define basic variables, like maximum page size, values for spacing rhythm
define breakpoints
define color variables, font-size variables, grid options, spacing variables
see settings

Tools

There are several mixins and functions to simplify and unify common used declarations like font-sizes, colors, breakpoints and spacing.

responsive font-size: @include font-size(base)
fixed font-size: @include font-size(base, sm, false)
use defined colors: color: color(base)
device-based breakpoints: @include breakpoint(md)
content-based breakpoints: @include breakpoint(920px)
use defined spacings: padding-top: spacing(m), for text-spacing: padding-bottom: text-spacing(l)

Grid

We implemented a sass generated grid. You are able to choose your preferred grid type (flex, float, inlineblock, CSS Grids coming soon), the amount of columns and the spacing between columns. The generated grid classes are mostly named like bootstrap, e.g.:

col-6, col-lg-6, col-md-6, col-sm-6, col-xs-6
col-offset-6, col-lg-offset-6, col-md-offset-6, col-sm-offset-6, col-xs-offset-6

Atoms, Elements, Modules

We are using a customized approach of Atomic Design. We decided to call molecules 'elements' and organisms 'modules'. Semantically they are pretty much the same.

Have a look at our template file for a suggested structure of attribute declarations and examples of usage.

Helper Classes

Instead of creating a variation of an element or atom class for unique styling cases we are using helper classes.

spacing: .mt-1, .mb-1, .n-mt-1, .mt-md-1, .pt-1, ...
font styling: .font-lg-base, .font-bold, .text-uppercase, ...
see helpers for more

3. JavaScript

Linting

To improve code quality and consistency we follow the Airbnb Javascript Style Guide. We use ESLint with the Airbnb config to comply with the style guide (ESLint config). To enable linting, check the preferences of your editor.

Module Classes

Our basic approach is to get as close as possible to Object Oriented Programming with JavaScript. For each module, create a class which implements the needed functionality. The Class Template defines a basic structure. The class constructor expects a Node Object as element. Optionally, further parameters can be provided.

Main

This is the main script from where all functions should be called and all classes should be created. Use the factory functions to create instances of your classes. See main.js how to use them.

The graceProduce function produces many instance of the class. For each Node with the given selector, an instance of the class is created. So each Node has its own class instance.
The graceCreate function creates one instance of the class. The element is an Array of each Node with the given selector.

Events, Functions and Libraries

You should add global event listeners inside the events.js file. Global events are not related to a module, like sending a Google Analytics event triggered by every button on the page.
If you are writing global functions, the folder functions is the right place.
If you need to include 3rd party libraries, add them to the libraries folder, and Gulp bundles them into a libs.js file.

Building

singles are processed as they are and are stored to the dist/js folder
libs get build into a libs.js, with the scripts inside the first folder being added at first
all other scripts get build into the main.js
support of EcmaScript6 via Babel Polyfill
additional browser support with the main.legacy.js

4. Inline SVG-Icons

We are using inline SVG-Icons. The build process gulp images optimizes the SVGs using SVGO, builds them into a PHP file and as .svg-files to the image folder. From there you can either import them by using the PHP variables or using the built-in Gulp File Include module.

inline import into HTML template via @@include(dist/img/icons/icon-atom.svg)

inline import for PHP e.g.:

<?php require 'icons.php'; ?>

<span class="icon"><?php echo $icon_atom; ?></span>

Gulp Tasks

gulp dev - used in development environment gulp build - used for production environment

Others

images optimized by mozjpeg, pngquant
BrowserSync
minified JS, CSS and HTML

Browser Support

last 4 versions, not ie <= 10, not Edge <= 13, Safari >= 8
see browserl.ist fore more information

Future Work

implement JS Features
add JS and SASS Linting
integrate automated test setup

We'd like to hear your opinion, any comments or suggestions to make it even better.

Built with <3 by Me & Company

me-and-company / grace

readme