NICE Icons

Icons for use in NICE Digital Services

Table of contents

• NICE Icons
  • Intro
    • Guidance
  • Upgrading from 1.x to 2.x
    • What's new in v2.x?
  • Installation
    • Include sass
      • Environment variable
      • includePaths
      • Tilde import
  • Usage
    • React
      • Browser support
    • Webfont
      • Serving font files
        • Express
        • Grunt copy
        • Visual Studio Copy Task
        • Webpack
      • Markup
      • SASS
  • Development
    • Dependencies
    • Commands
    • Updating the readme
    • Releasing
  • Creating icons
  • Custom application icons
  • Icons
  • License

Intro

NICE Icons is a replacement for NICE.Glyphs. It is independent of Bootstrap and the Design System so can be used on its own.

Guidance

Avoid unnecessary decoration - only use icons if there’s a real user need:

• if icons are needed ensure they are clear, simple and accompanied by relevant text
• don’t hide functionality under icons
• icons should be easily recognizable
• keep icon designs simple and schematic.

Upgrading from 1.x to 2.x

The following are breaking changes from v1 to v2:

• the generated SASS file is at a new path - now at /scss rather than dist/ to be consistent with other packages
• the SASS base path variable $nice-font-base-path is now $nice-icons-base-path
• the SASS mixin icon-base is now nice-icons-base
• there are no nested folders within src
• dropped speak: none CSS property
• dropped support for usage via Bower
• use Node 10, and npm 6.8+.

What's new in v2.x?

As well as the breaking changes listed above, we've made the following updates:

• upgrade to Babel 7
• upgrade other outdated packages
• add Figma source file containing all the SVG icons
• add React components, with ES5 transpiled version.

Installation

Install NICE Icons from npm:

npm i @nice-digital/icons --save

The node_modules/@nice-digital/icons package folder will include:

• source SVG files in the src folder
• React components in the lib folder
• generated icon font (EOT, SVG, TTF, WOFF and WOFF 2) in the dist folder
• JSON file in the dist folder with font metadata information.

Include sass

Import NICE Icons in SASS with:

@import 'nice-icons';

But before you do this, you'll need to include the path ./node_modules/@nice-digital/icons/scss in your SASS build. There are a few ways to do this:

Environment variable

Use the SASS_PATH environment variable with SASS. For example, in Create React App 2 use the following inside a .env file:

SASS_PATH=node_modules/@nice-digital/icons/scss

includePaths

Use the includePaths option from node-sass to include the path. Or with grunt-sass:

// Gruntfile.js
module.exports = function(grunt) {
	// Run `npm i grunt-sass --save-dev`
	grunt.loadNpmTasks("grunt-sass");

	grunt.initConfig({
		sass: {
			app: {
				includePaths: ["node_modules/@nice-digital/icons/scss"]
			}
		}
	});
};

Tilde import

Replace the import above with a tilde path if you're using sass-loader via webpack or node-sass-tilde-importer with node-sass:

@import '~@nice-digital/icons/scss/nice-icons';

Usage

We've created various usage examples to help with getting started.

There are 2 main ways to use NICE Icons in your project:

React

There are React component versions of each icon within the lib folder. This allows you to easily include inline SVGs when rendering via React. Each icon file is named with PascalCase, for example src/email-closed.svg is available in React as lib/EmailClosed.js.

To use, first import the SASS file into your project as above. Then import and use React components from the lib folder, for example:

import Search from "@nice-digital/icons/lib/Search";

const something = (props) => {
	return <div>
		<Search />
	</div>;
};

The React component icons have the following default props:

• className=icon - the associated class has a height and width of 1em to match the surrounding text
• aria-hidden={true} as they're designed to be a visual to textual labels. In the rare case you need icons on their own without text, then pass a prop of aria-hidden={false} and make sure there's an associated aria label, title etc.

The svg path also has a default fill=currentColor to match surrounding text colour, but this can also be overridden by the colour prop, or via CSS.

Note: these React files in the lib folder are ES5 compatible. However, we also include ES6 versions in the ES6 folder if you prefer. This means you'll need to transpile these with babel (or similar) as part of your build. For example, by using the include option pointing to node_modules/@nice-digital/icons with babel-loader in webpack.

Browser support

This method is subject to the same browser support as inline SVGs - essentially IE9+. To support IE8, you'd need to roll your own fallback - that's currently beyond the scope of this package.

Webfont

We provide a custom icon web font because:

• it's easy to render custom icons with content managed markup
• there's no JavaScript required
• icon color, size, shadow etc can be styled with CSS
• any custom icons can be used
• icon fonts support IE8+
• vector icons are infinitely scalable
• vector icons look perfect on retina displays.

Serving font files

Note: Add the corrrect MIME type to your web.config if you get a 404 error for .woff files in IIS.

Express

Use express.static to serve font files in Express directly from the dist folder:

const express = require("express"),
	path = require("path");

const app = express();

app.use("/fonts", express.static(path.join(__dirname, "./node_modules/@nice-digital/icons/dist")))

See the simple-express folder for a complete example of this.

Grunt copy

Setup a copy task with Grunt to copy the font files into your application:

// Gruntfile.js
module.exports = function(grunt) {
	// Run `npm i grunt-contrib-copy --save-dev`
	grunt.loadNpmTasks("grunt-contrib-copy");

	grunt.initConfig({
		copy: {
			icons: {
				cwd: "node_modules/@nice-digital/icons/dist/",
				src: ["*.{eot,woff,woff2,ttf,svg}"],
				dest: "/fonts/",
				expand: true,
				flatten: true,,
				filter: "isFile"
			}
		}
	});
};

Visual Studio Copy Task

Use a Visual Studio Copy Task to copy the font files into your application. Or use a post build event.

Webpack

Install Copy Webpack Plugin into your application, then at the top of your webpack config file add the following:

const CopyWebpackPlugin = require('copy-webpack-plugin');

then in the plugins section add the following:

new CopyWebpackPlugin([{ from: "node_modules/@nice-digital/icons/dist/*", to: "fonts", ignore: ["*.html"], flatten: true }]),

note that the 'to' destination is relative to the output path, which for a .NET core app would probably have been configured for wwwroot.

Markup

Use custom icons in markup (rather than SASS) wherever possible:

• hide from screenreaders with [aria-hidden="true"]
• use BEM style CSS classes (icon--NAME modifier)
• prefer <span> over <i>.

Basics of usage are: <span class="icon icon--[NAME]" aria-hidden="true"></span> where name is one of the source icons e.g.:

<span class="icon icon--logo" aria-hidden="true"></span>

SASS

There are SASS constructs for advanced usage:

• @mixin nice-icons-base for the base styles required for an icon
• @mixin nice-icon($icon)n e.g. @include nice-icon(logo);
• @function nice-icon($icon) e.g. content: nice-icon(logo); - gets the unicode codepoint value
• $nice-icons - a map of icon name to unicode codepoint. Override this when generating a custom webfont in your application
• $nice-icons-base-path - the URL from which to download the font files. Override this in your application if you serve font files from a different path.

.logo {
	&__btn {
		@include nice-icon(logo);
	}

	// or
	&__btn {
		@include nice-icons-base;

		&:before {
			content: nice-icon(logo);
			display: block;
		}
	}
}

Development

Dependencies

TL;DR:
	1. `npm i`
	2. `npm start`

To build the icon font on your local machine, first install:

• Node 12, or even better use Volta which will use the Node version pinned in package.json
• npm 6

Then before you can run any tasks, run the following from the command line to install dependencies:

• npm i

Note: if you prefer to use npm rather than yarn, run yarn instead.

We use Grunt as a task runner hence the dependency on Node. If you haven't used Grunt before, be sure to check out the Getting Started guide first.

Commands

Run npm start from the command line for development. This uses grunt-webfont under the hood to:

• build the source icons into a web font in the dist folder with formats:
  • EOT
  • SVG
  • TTF
  • WOFF
  • WOFF2
• build a JSON file of metadata for the font
• build a SASS file
• build React components into the lib folder
• create a demo html - use this for testing new icons.

Updating the readme

Run the following command to update the readme:

npm run readme

This will generate the table of icons from the readme and to update the ToC.

Releasing

Run npm run release from the command line to release the package in interactive mode. Or run one of:

• npm run release:major
• npm run release:minor
• npm run release:patch

Alternatively use fine-grained options like npm run release -- 2.0.0-beta.1 --tag=beta --any-branch

This uses np under the hood.

Note: Generate a GitHub personal acccess token and set this as the environment variable GITHUB_TOKEN. E.g. export GITHUB_TOKEN="abcde1234"

Creating icons

We provide a [Figma file](NICE Icons.fig) with the source of all icons. Upload this into Figma and add a new Page for each icon.

Follow the following steps to create a new SVG in Figma:

1. Add page with the correct name eg "Address book"
2. If you have an existing SVG, drag it into the page pane. If creating a custom SVG, ensure you have a single compound path vector.
3. Set X and Y to 0 and 0
4. Add a 32px layout grid to the frame
5. Rename the frame (with the hash symbol) to "Address book frame" and the vector within it to "Address book vector"
6. On the vector, change the constraints to Centre and Centre.
7. On the frame change the width and height to 512px.
8. On the vector, SHIFT+Click the corner resize tool and give it 1 square padding
9. Centre the vector using the icons at the top of the design tool panel or use ALT+V and ALT+H when the vector is inside the frame.
10. On the Address book page, add an export setting with type of SVG, then export the SVG changing the filename to kebab case eg "address-book.svg" and save in the src folder. (Alternatively, right-click the frame and Copy As SVG)
11. Ensure the SVG file has the XML declaration at the top, the same as all the other SVG files in the repository.
12. In Figma menu, File > Save as .fig and save a new copy of NICE Icons.fig, in the root of the repository.

Afterwards,

1. Re-run npm start to rebuild the icon font and React components
2. Re-run npm run readme to rebuild the icons in this readme file.

Custom application icons

Use these instructions to build a webfont from custom icons for your application. First, follow the steps above to create an SVG then follow the steps below to create a custom icon font:

1. Create a grunt task for webfont generation. You can base this off our webfont task.

2. Use a custom template to override the $nice-icons map. (You don't need the mixins in your template.)

3. Reference both your SVG icon and the core icons:

   src: ["./icons/*.svg", "./node_modules/@nice-digital/icons/src/*.svg"]

4. Override the $nice-icons-base-path variable in your application's SASS to match where your font files are served from. The default path is /fonts/.

Note: Only reference the core icons you need when building a custom icon font. E.g. replace "./icons/*.svg" with "./icons/logo.svg", "./icons/search.svg" etc.

See the custom-icon folder for a complete example of this.

Icons

Icon	Name	Unicode	HTML	SASS
	android	f17b	<span class="icon icon--android" aria-hidden="true"></span>	@include nice-icon(android);
	apple	f179	<span class="icon icon--apple" aria-hidden="true"></span>	@include nice-icon(apple);
	calendar	e045	<span class="icon icon--calendar" aria-hidden="true"></span>	@include nice-icon(calendar);
	check	f00c	<span class="icon icon--check" aria-hidden="true"></span>	@include nice-icon(check);
	chevron-down	e03c	<span class="icon icon--chevron-down" aria-hidden="true"></span>	@include nice-icon(chevron-down);
	chevron-left	e03b	<span class="icon icon--chevron-left" aria-hidden="true"></span>	@include nice-icon(chevron-left);
	chevron-right	e03a	<span class="icon icon--chevron-right" aria-hidden="true"></span>	@include nice-icon(chevron-right);
	chevron-up	e039	<span class="icon icon--chevron-up" aria-hidden="true"></span>	@include nice-icon(chevron-up);
	comment	f101	<span class="icon icon--comment" aria-hidden="true"></span>	@include nice-icon(comment);
	download	e006	<span class="icon icon--download" aria-hidden="true"></span>	@include nice-icon(download);
	email-closed	e014	<span class="icon icon--email-closed" aria-hidden="true"></span>	@include nice-icon(email-closed);
	evidence	e017	<span class="icon icon--evidence" aria-hidden="true"></span>	@include nice-icon(evidence);
	facebook-square	f082	<span class="icon icon--facebook-square" aria-hidden="true"></span>	@include nice-icon(facebook-square);
	facebook	e012	<span class="icon icon--facebook" aria-hidden="true"></span>	@include nice-icon(facebook);
	google-plus-square	f0d4	<span class="icon icon--google-plus-square" aria-hidden="true"></span>	@include nice-icon(google-plus-square);
	google-plus	f0d5	<span class="icon icon--google-plus" aria-hidden="true"></span>	@include nice-icon(google-plus);
	guidance	e011	<span class="icon icon--guidance" aria-hidden="true"></span>	@include nice-icon(guidance);
	hamburger	e03d	<span class="icon icon--hamburger" aria-hidden="true"></span>	@include nice-icon(hamburger);
	instagram	f16d	<span class="icon icon--instagram" aria-hidden="true"></span>	@include nice-icon(instagram);
	linkedin-sign	f08c	<span class="icon icon--linkedin-sign" aria-hidden="true"></span>	@include nice-icon(linkedin-sign);
	linkedin	f0e1	<span class="icon icon--linkedin" aria-hidden="true"></span>	@include nice-icon(linkedin);
	logo-full	e01c	<span class="icon icon--logo-full" aria-hidden="true"></span>	@include nice-icon(logo-full);
	logo-name	e01b	<span class="icon icon--logo-name" aria-hidden="true"></span>	@include nice-icon(logo-name);
	logo	e01a	<span class="icon icon--logo" aria-hidden="true"></span>	@include nice-icon(logo);
	minus	e02a	<span class="icon icon--minus" aria-hidden="true"></span>	@include nice-icon(minus);
	pathways	e005	<span class="icon icon--pathways" aria-hidden="true"></span>	@include nice-icon(pathways);
	play	e028	<span class="icon icon--play" aria-hidden="true"></span>	@include nice-icon(play);
	plus	e027	<span class="icon icon--plus" aria-hidden="true"></span>	@include nice-icon(plus);
	podcast	e00b	<span class="icon icon--podcast" aria-hidden="true"></span>	@include nice-icon(podcast);
	print	e001	<span class="icon icon--print" aria-hidden="true"></span>	@include nice-icon(print);
	question-circle	f059	<span class="icon icon--question-circle" aria-hidden="true"></span>	@include nice-icon(question-circle);
	readnews	e009	<span class="icon icon--readnews" aria-hidden="true"></span>	@include nice-icon(readnews);
	remove	e024	<span class="icon icon--remove" aria-hidden="true"></span>	@include nice-icon(remove);
	search	e004	<span class="icon icon--search" aria-hidden="true"></span>	@include nice-icon(search);
	share	e008	<span class="icon icon--share" aria-hidden="true"></span>	@include nice-icon(share);
	sorting-asc	e022	<span class="icon icon--sorting-asc" aria-hidden="true"></span>	@include nice-icon(sorting-asc);
	sorting-desc	e023	<span class="icon icon--sorting-desc" aria-hidden="true"></span>	@include nice-icon(sorting-desc);
	sorting	e021	<span class="icon icon--sorting" aria-hidden="true"></span>	@include nice-icon(sorting);
	standards	e002	<span class="icon icon--standards" aria-hidden="true"></span>	@include nice-icon(standards);
	stop	e043	<span class="icon icon--stop" aria-hidden="true"></span>	@include nice-icon(stop);
	syndication	e013	<span class="icon icon--syndication" aria-hidden="true"></span>	@include nice-icon(syndication);
	trash	e020	<span class="icon icon--trash" aria-hidden="true"></span>	@include nice-icon(trash);
	twitter-square	f081	<span class="icon icon--twitter-square" aria-hidden="true"></span>	@include nice-icon(twitter-square);
	twitter	e000	<span class="icon icon--twitter" aria-hidden="true"></span>	@include nice-icon(twitter);
	user	e01f	<span class="icon icon--user" aria-hidden="true"></span>	@include nice-icon(user);
	warning	e04b	<span class="icon icon--warning" aria-hidden="true"></span>	@include nice-icon(warning);
	youtube-play	f16a	<span class="icon icon--youtube-play" aria-hidden="true"></span>	@include nice-icon(youtube-play);
	youtube-square	f166	<span class="icon icon--youtube-square" aria-hidden="true"></span>	@include nice-icon(youtube-square);

License

NICE Icons distributed under the MIT license.

We use some icons from the awesome Font Awesome Free, which is licensed under the CC BY 4.0 license.