node package manager
Easy sharing. Manage teams and permissions with one click. Create a free org »

spk-workflow

Settings  |  BrowserSync  |  CSS  |  Fonts  |  Icons  |  Images  |  JavaScript

Spektrum Media front-end workflow

Workflow built on Gulp using Sass, PostCSS, Gulp-Fontgen, Gulp-Iconfont and BrowserSync.

Upon first installation, the front-end document architecture will be generated automatically.

Requirements

  • NodeJS | < 5.11.x
  • NPM
  • JDK | To check if you have a JDK installed:
    java -version
  • FontForge and its dependencies (batik, ttf2svg) | To install with homebrew:
    brew install fontforge batik ttf2svg

Installation

In your terminal, run npm init from your project's front-end folder and fill in the fields appropriately.

Then run npm install spk-workflow --save-dev.

Usage

The main tasks are

  • ######gulp launch browserSync and gulp-watch

  • ######gulp dev launch only gulp-watch

  • ######gulp build process Sass/PostCSS and run JSHint

  • ######gulp build-full process Sass/PostCSS, build fonts and icons and run JSHint

  • ######gulp images optimize images through the TinyPNG API (requires free API key)

Settings

Settings are set at the top of gulpfile.js in the settings object.

The settings are:

  • #####browserSync.useBrowser ######string | array Leave as default to use your default browser. You can also assign an array if you want to open multiple browsers at once, eg. ['google chrome', 'firefox'].

  • #####browserSync.useProxy ######string | boolean To use BrowserSync and serve your files from a dev server, you need to set your local proxy URL such as project.local or localhost/project. Leave as false if you are just serving static files.

  • #####errors.notifications and errors.sounds ######boolean Use system notifications and/or sounds when errors occur that prevent successful completion of a task.

  • #####keys.tinypng ######string | boolean Input your TinyPNG API key if you wish to use the image optimization feature.

Project Structure

./
  ├─ Fonts/
  │
  ├─ Icons/
  │  └─ _Src/
  │
  ├─ Images/
  │
  ├─ Sass/
  │  ├─ site.scss
  │  │
  │  ├─ Assets/
  │  │  ├─ _fontface.scss
  │  │  └─ _icon.scss
  │  │
  │  ├─ Components/
  │  │
  │  ├─ Settings/
  │  │  ├─ _body.scss
  │  │  ├─ _color.scss
  │  │  ├─ _easing.scss
  │  │  ├─ _font.scss
  │  │  └─ _mediaquery.scss
  │  │
  │  └─ Tools/
  │     ├─ _mixin.scss
  │     └─ _reset.scss
  │
  ├─ Scripts/
  │  └─ site.js
  │
  └─ Stylesheets/

 

BrowserSync

For full documentation, see the BrowserSync website.

The default gulp task will launch BrowserSync on port :3010 and will reload the page on save for .scss, .js, .html and .cshtml files.

CSS

Features  |  Tools  |  Syntax
Task: gulp css
Connected tasks: gulp build, gulp build-full, gulp, gulp dev

Features

The processor uses gulp-sass in it's default configuration. Please refer to the Sass Documentation for more information.

PostCSS processes Sass' output to add a few extra features and shortcuts.

PostCSS features include:

Tools

The SPK Workflow includes three team-sourced tools:

A collection of mixins and a reset stylesheet that are maintained by the team. The goal is to reduce the amount of obfuscated code and apply a CSS reset that everyone is familiar with.

During each project's post-mortem, any additions or modifications will be discussed to help these tools evolve.

The last file is contains all the team-sourced Sass functions.

ColorControl

The cc() ColorControl function allows great centralized control and coordination of your color palettes and variations.

Colors are set in Sass/Settings/_color.scss as a Sass map. All colors should be set in the default sub-map default. Any modifications should be created in a relevant sub-map.

To call your colors, use the cc() function. The first parameter, the color you want, is mandatory and will be pulled from the default palette. The second parameter can be either the sub-palette you want or the alpha-channel. If you specify a sub-palette, you can pass the alpha-channel as the third option.

Example:

/* _color.scss */
$colors: (
    default: (
        white: #fff,
        blue: #427fab,
        grey: #4b4b4b
    ),
    about: (
        white: #fafafa,
        blue: #427fcc
    )
);
 
/* _body.scss */
body {
    color: cc(white);
    background: cc(blue.5);
}
 
/* _about.scss */
.about {
    color: cc(white, about);
    background-color: cc(blue, about, .5);
    border-color: cc(grey);
}

Syntax

As mentioned above, Sass is used as a first layer of processing. Using usual Sass syntax as you are used to will work perfectly.

The PostCSS layer offers extra features and is intended to stay completely out of the way when not called upon. Using these is completely optional.

Custom Media Queries

Set media query aliases and use them with a much more natural syntax. ######Input

@custom-media --md (min-width: 48em); // >= 768px
 
.row {
    padding: 2.25vw;
 
    @media (--md) {
        display: flex;
        align-items: stretch;
        @include clearfix;
    }
 
    &__item {
        margin-bottom: 1.5em;
 
        @media (--md) {
            flex: 1 0 0;
            float: left;
            margin-bottom: 0;
        }
    }
}
Output
.row {
    padding: 2.25vw;}
 
    .row__item {
        margin-bottom: 1.5em;}
 
@media (min-width: 48em) {
    .row {
        display: flex;
        align-items: stretch;}
 
        .row::after {
            content: '';
            display: block;
            height: 0;
            visibility: hidden;
            clear: both;}
 
        .row__item {
            flex: 1 0 0;
            float: left;
            margin-bottom: 0;}
}

Shorthand Properties

There are 3 property shortcuts available:

  • size
  • color
  • position
Input
/* size */
.box {
    size: 50% 250px;
 
    &--square {
        size: 250px;
    }
 
    &--fill {
        size: 100%;
    }
}
 
/* color */
.button {
    color: #456990;
 
    &--alt {
        color: #fff #456990;
    }
}
 
/* position */
.nav {
    fixed: top left;
}
 
.titleDecoration {
    absolute: bottom -.25em right 50%;
    transform: translateX(50%);
}
Output
/* size */
.box {
    width: 50%;
    height: 250px;}
 
    .box--square {
        width: 250px;
        height: 250px;}
 
    .box--fill {
        width: 100%;
        height: 100%;}
 
/* color */
.button {
    color: #456990;}
 
    .button--alt {
        color: #fff;
        background-color: #456990;}
 
/* position */
.nav {
    position: fixed;
    top: 0;
    left: 0;}
 
.titleDecoration {
    position: absolute;
    bottom: -.25em;
    right: 50%;
    transform: translateX(50%);}

 

Fonts

Task: gulp fonts
Connected tasks: gulp assets, gulp build-full

Simply drop any .ttf or .otf files in the ./Fonts/ folder.

The eot, ttf, svg, woff, woff2 font files are generated in their own sub-directories.

The CSS @fontface declarations are also generated automatically and added to ./Sass/Assets/_fontface.scss. ###  

Icons

Task: gulp icons
Connected tasks: gulp assets, gulp build-full

Drop any .svg files into ./Icons/_Src/.

The first step will create an SVG-Spritesheet with <symbol> elements in ./Icons/. You can then add the spritesheet to the top of the document's body using AJAX, leveraging the browser's cache for future visits.

You can use these as icons with the SVG <use> element, setting the reference to the filename of the original SVG file. For example, if you had a file named potato.svg:

<svg class="u-svgIcon"><use xlink:href="#potato"></use></svg>

You can style the icon through CSS. Instead you using color: blue; for it's color, you would use fill: blue;.

The second step will generate eot, ttf, svg, woff, woff2 font files and the necessary CSS @fontface declarations and classes, which are added to ./Sass/Assets/_icons.scss

Again, the original file name is used to identify the icon you want by class prefixed with i-.

using the same example as above:

<i class="i-potato"></i>

Each task is individually accessible through gulp icons-sprite for the svg icons and gulp icons-font for the icon fonts. ###  

Images

Task: gulp images

Note: this task requires an Internet connection.

Any .png, .jpg, .jpeg file in ./Images/ will be optimized, but only once to prevent making unnecessary calls to the TinyPNG API, for which you need a free API key.

If a filename is changed, it will be optimized again.

JavaScript

Task: gulp js
Connected tasks: gulp build, gulp build-full, gulp, gulp dev

JS processing consists only of linting your scripts with JSHint and outputting any errors and warnings to your terminal.