@nice-digital/icons v6.0.1

NICE Icons

Icons for use in NICE Digital Services

• Intro
  • Some background
  • Guidance
• Upgrading from 1.x to 2.9
  • What's new in v2.0?
  • What's new in v2.3?
• Installation
  • Include sass
• Usage
  • React
    • Browser support
  • Webfont
    • Serving font files
      • Express
      • Visual Studio Copy Task
      • Webpack
    • Markup
    • SASS
• Development
  • Dependencies
  • Commands
  • Updating the readme
• Creating icons
• Icons
• License

Intro

NICE Icons is a set of SVG icons for use in NICE Digital Services using the NICE Design System. It provides source SVGs, React/TypeScript versions and an icon font.

Some background

NICE Icons is a replacement for NICE.Glyphs, which in turn was part of the old 'NICE.Bootstrap'.

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.9

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.0?

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.

What's new in v2.3?

Version 2.3 is an internal refactor, mostly to use fantasticon instead of grunt-webfont for the icon font generation. This release drops support for IE8, which we no longer support but that should be the only 'breaking' change.

We have removed generation of EOT, SVG and TTF font files because we know longer support older browsers like IE8 that needed these types. We now just generate WOFF and WOFF2 which covers all modern browsers.

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:
  • ES5 in the lib folder (with associated d.ts files)
  • ES6 in the es folder (with associated d.ts files)
  • TypeScript in the ts folder
• generated icon font (WOFF and WOFF 2) in the dist folder
• generated SCSS in the scss folder
• JSON file in the dist folder with font metadata information.

Include sass

Import NICE Icons in SASS with:

@use '@nice-digital/icons/scss/nice-icons';

Usage

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 (transpiled to ES5) or the es folder (ES6 compatible). 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 via CSS.

Note: these React files in the lib folder are ES5 compatible. However, we also include ES6 versions in the es 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+.

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.

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 14
• npm 6.8+

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

Commands

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

• build the source icons into a web font in the dist folder with formats: - WOFF - WOFF2
• build a JSON file of metadata for the font
• build a SASS file
• build React components into the lib and es folders
• 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.

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.

Note: Figma is an online (and desktop) design and wireframing-type application. We're using it here in the context of a vector drawing tool, like Adobe Illustrator. The steps below will essentially take you through opening the existing project file with all the icons in, adding a new one in the "right" way (so it's a standard format with all of the other icons), exporting your new icon as an SVG to add to the repo, and re-saving the project file ready for the next person.

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.

Icons

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.