Coop-frontend-toolkit NPM

Co-op Front-end Toolkit

The Co-op Front-end Toolkit contains all the core assets needed to build Co-op-branded digital content.

For more information on all the available styles and modules, please refer to the Co-op Design Manual.

Installation

Install the Toolkit by adding it as a NPM package to your project:

npm install coop-frontend-toolkit --save

Usage

Simply import the style components you require into your own stylesheet:

/* my_styles.scss */
@import 'node_modules/coop-frontend-toolkit/styles/fonts';
@import 'node_modules/coop-frontend-toolkit/styles/forms';
/* Import some more and add your own styles */

You can override default variables by setting your own. Copy /styles/_variables.scss into your project and start modifying typographic scale, colours and other settings (you can omit the settings you want to keep as is), then import it before importing toolkit components:

/* _my_variables.scss */
$base-line-height: 1.25;
$body-copy: #bbb;

/* my_styles.scss */
@import 'my_variables';
@import 'node_modules/coop-frontend-toolkit/styles/coop-toolkit';

Static assets

You will need to copy the static assets found in /static/ to your project as required.

The default path for those assets is set by the variable $base-asset-url, which you can update as required. For instance, if your assets will be served at /assets/static/, set $base-asset-url: '/assets/static/';.

Any asset referenced in your CSS using the asset-url function will then resolve to the set path automatically:

$base-asset-url: '/assets/static/';

@import 'node_modules/coop-frontend-toolkit/functions';

body {
  background-image: asset-url('images/background.jpg');
}

/* Will result in:
body {
  background-image: url('/assets/static/images/background.jpg');
}
*/

Older version of the Toolkit

The base styles provided by the Toolkit changed quite a bit between version 1.1.3 and version >= 2.0.0, unfortunately resulting in a couple of breaking changes. The older versions (up to 1.1.3) are available on the Co-op Digital organisation repository on Github.

If you need to carry on using the older styles, you need to make sure you are using version 1.1.3 of the Toolkit. To do so use the full github URL, including the version number:

{
  "name": "project-name",
  "dependencies": {
    "coop-frontend-toolkit": "coopdigital/coop-frontend-toolkit#1.1.3"
  }
}

Breaking changes between 1.1.3 and 2.0.0

If you want to update to version 2, you need to be aware of the following breaking changes.

Typographic scale

If you have set a custom typographic scale, this will need to be updated to contain all the necessary base properties. Here are the defaults now set, all of which need to be present in the base property of your custom scale:

$typographic-scale: (
  base: (
    body: 16px,
    h-mega: 46px,
    h1: 30px,
    h2: 20px,
    h3: 18px,
    h4: 18px,
    h5: 18px,
    h6: 13px,
    blockquote: 20px,
    lead: 20px,
    small: 13px,
    base-line-height: 1.7,
    base-spacing-unit: 32px,
  )
}

Checkboxes and Radio buttons

Checkboxes and radio buttons followed directly by a <label> element will need a small tweak to display on the same line. The following CSS handles this realignment:

input[type="checkbox"],
input[type="radio"] {
  display: inline-block;
  width: auto;
}

input[type="checkbox"] + label,
input[type="radio"] + label {
  display: inline-block;
  margin: 0 0 0 5px;
  vertical-align: middle;
}

JavaScript modules

The Javascript modules (Tabs and Toggles) have been removed from the Toolkit. If you wish to carry on using those, you will need to copy them over from version 1.1.3 to your project manually, as well as the modules loader.

Usage

These assets should be compiled into production-ready versions (minified for CSS/JS, optimised for images), using a task runner or an asset pipeline. An example using Gulp can be found in the Co-op Style Guide repository.

This repository will eventually contains a set of best practices and recommendations for serving fast, optimised web pages to the users.

Available assets

This Toolkit contains SASS stylesheets, JavaScripts and static assets (fonts and images).

Stylesheets

The core styles are available as SASS stylesheets. Most are available as mixins, so you can choose to apply the styles using your own class names. The main stylesheet _coop-toolkit.scss contains the complete collection of available core styles and components and is a good starting point for building your project's final stylesheet.

IE-specific styles

Some stylesheets may need to contain Internet Explorer-specific styles, to cater for the older versions of IE that still require support. This is done through the use of the ie($version) mixin, which adds the styles to the outputted CSS if the variable $ie is lower than the specified version. To make use of those styles, a separate stylesheet should be created for IE browsers, which should be served using conditional comments:

<!-- This stylesheet will be served to IE 9: -->
<!--[if IE 9]><link rel="stylesheet" type="text/css" href="/css/ie-9.css"><![endif]-->

<!-- This stylesheet will be served to all other browsers: -->
<!--[if gt IE 9]><!--><link rel="stylesheet" type="text/css" href="/css/main.css"><!--<![endif]-->

Static assets

The static assets contain the necessary fonts (Avenir, Coopicons) used by the styles, as well as SVG and PNG versions of the Co-op logo. These should be copied over to your project's assets directory by whichever task runner or asset pipeline you are using.