🚨 Do not modify this package as it is used in the next version of Cirrus. We are keeping them here for compatibility purpose only.

Icon

Icon Component

Installation

First, make sure you have been through the Getting Started steps of adding Cirrus in your application.

If using Yarn:

yarn add @lightspeed/cirrus-icon

Or using npm:

npm i -S @lightspeed/cirrus-icon

Contributing

Icons as React components are automatically generated with a build script. To see changes when adding/updating an icon, add your .svg in the svg folder, navigate to this directory in the terminal, and run this command to re-generate the build:

yarn generate-icons

This script will generate the React components and the Icon sprite.

Note that this command will be run automatically when in local development and when we publish to npm.

Designing icons

Our main icon style has been changed from an outlined look to a so-called glyph style. This form will bring a bit more body to the icons and reduces the amount of white in the screens as well. They still have the unique Lightspeed style and are friendly to look at.

The Sketch file for these icons can be found in the Cirrus Abstract project as a library.

Using icons

Using icons is an excellent way to manage expectations inside navigation and actions. It also makes the overall experience visually more pleasing. The hard part of creating an icon is picking the right metaphor. Always do a little research and iterations to make sure you will be using the brightest and most legible metaphor.

By linking the Cirrus Icons library, you have access to all available icons inside Sketch. Alternatively, you can grab the source SVG file from the Cirrus repository.

Anatomy of a Cirrus icon

There aren't many rules that apply to achieve our style, but the ones there can be found in this section.

Corners and edges

To make them feel as friendly as they are, try to avoid hard corners at all times. On a 16x16 icon you can use 0.25px,0.5px or 1px border-radius instead. To make them sharp and better scalable try to avoid vector points being off pixel except 0.25,0.5 and 0.75are allowed only if you can't use a full pixel value.

Strokes and Fills

Try to avoid strokes as much as possible, and use fills instead.

Elements and their color

Each icon exists with a maximum of four different layers and two colors, a base, and a detail color. Use the pre-defined layer styles at all times

| Layer | Usage | | ----- | ----- | | base-1 | This is the main body of an icon and is always the base colour | | base-2 | Some icons have two elements for their base shape. When this is the case, the base-2 layer is the element that is the least important in the hierarchy. The color of this element is the base color with 70% opacity. | | details-1 | When there is space and need for a little bit of details inside the icon we use the detail color. in addition, the shape of the details-1 layer should always be extracted from the base-1 layer. | | details-2 | Similar to base-2 except this is used on a detail level and therefor uses the detail color on 70%. By default this color is cr-snow |

Exporting icons

All icons should be exported from the Cirrus Icons.sketch file of the Cirrus repository in Abstract. Exporting should be done from the Slices in each of the icons (on the Symbols page), and not the Symbol Artboards.

Before exporting try to flatten out shapes as much as possible, the fewer shapes you have in place the better the icon will perform, also try to limit the number of anchor points inside your shapes.

If an Icon contains details-1, paths overlapping base-1 should be also be cut out (using the Sketch Layer -> Combine -> Subtract command).

When adding new SVGs make sure it has the following rules are applied:

1. All paths live inside a group with the icon name inside the id in lowercase
2. Sketch layers are called either "base-1", "base-2", "details-1" or "details-2"
3. details-1 paths have no fill property in Sketch
4. details-2 paths have a "#fff" white fill
5. base-2 and details-2 have opacity of 70%
6. Export the SVG (via the Export button, or by selecting the slice for the icon to be exported)
7. Save the Sketch-generated SVGs to the svg/ folder.

When a new .svg is added, a pre-commit hook will automatically take care of cleaning svg files for consumption by Cirrus. There is no need to manually alter svg files once they've been added or committed.

Usage

Import required styles in your .scss:

@import '@lightspeed/cirrus-icon/Icon.scss';

React Component

Props

Color properties can be any Cirrus color token, ex green-100 or any CSS value.

| Prop | Type | Description | | --------------- | ------------ | ------------------------------------------------------- | | className | string | Custom className to add in addition to the default ones | | name | string | Name of the icon | | size | string | Default 1rem, can be set to any custom value | | color | string | Applied on the svg fill property | | baseColor | string | Applied on the base paths fill property | | baseColor1 | string | Applied on the base-1 path fill property | | baseColor2 | string | Applied on the base-2 path fill property | | detailsColor | string | Applied on the details paths fill property | | detailsColor1 | string | Applied on the details-1 path fill property | | detailsColor2 | string | Applied on the details-2 path fill property |

Example

import React from 'react';
import Icon from '@lightspeed/cirrus-icon';

const MyComponent = () =>
  <div>
    <Icon name="settings" />
  </div>;

export default MyComponent;

CSS Component

To use the CSS component, you first need to inline the icon-sprite.svg content in your HTML, and then reference the icons like this:

<svg class="cr-icon cr-icon-add">
  <use xlink:href="#cr-icon-add" />
</svg>

You can also customize the fill properties with CSS Variables, for example with the above HTML:

.cr-icon-add {
  --cr-icon-base-1-fill: $cr-maple;
  --cr-icon-details-1-fill: $cr-maple-300;
}

The following variables are available depending on the level of details for a given icon:

• --cr-icon-base-1-fill
• --cr-icon-base-2-fill
• --cr-icon-details-1-fill
• --cr-icon-details-2-fill

with the corresponding utility classes:

• .cr-icon-base-1-{color}-{value}
• .cr-icon-base-2-{color}-{value}
• .cr-icon-details-1-{color}-{value}
• .cr-icon-details-2-{color}-{value}

For example:

<span class="cr-icon-base-1-maple cr-icon-base-2-maple-300 cr-icon-details-1-snow cr-icon-details-2-snow">
  <svg class="cr-icon cr-icon-add">
    <use xlink:href="#cr-icon-add" />
  </svg>
</span>

This will take care of setting the variables for you.

Look at the Sprite Story for more information.