[![Build Status][build_badge_image]][build_badge_link]
[![@armor/api][npm_badge_image]][npm_badge_link]
[![Managed With][managed_badge_image]][managed_badge_link]

[build_badge_image]:https://jenkins.secure-shared.services:443/buildStatus/icon?job=github.com-armor/armor-core-icons/master
[build_badge_link]:https://jenkins.secure-shared.services/job/github.com-armor/job/armor-core-icons/job/master/
[npm_badge_image]:https://img.shields.io/npm/v/@armor/icons.svg
[npm_badge_link]:https://www.npmjs.com/package/@armor/icons
[managed_badge_image]:https://img.shields.io/badge/managed%20with-terragrunt-%235849a6.svg
[managed_badge_link]:https://github.com/armor/infrastructure-live/tree/master/github/armor/repositories/api/terraform.tfvars

# @armor/icons

Webfont icons for Armor web applications.

## Prerequisites

- Ruby
- [NodeJS](https://github.com/armor/meta/tree/master/setup/node)
- [FontCustom](https://github.com/FontCustom/fontcustom)

## Installation

All dependencies are installed with NPM by running `npm install`.

## Usage

This package is included as a dependency of [Brandkit](https://github.com/armor/brandkit).
In most cases applications that will use this package, will also use Brandkit. If you only
need to use the icons, directly install the `@armor/icons` package:

```bash
npm install --save-dev @armor/icons
```

Then reference the icons in your project's Sass file:

```scss
@import "../../node_modules/@armor/icons/src/icons-core";
@import "../../node_modules/@armor/icons/src/icons-infrastructure";
@import "../../node_modules/@armor/icons/src/icons-security";
```

### Icons in Markup

To include an icon in markup, add the `.ico` class for the specific icon you want to add.

```html
<i class="ico ico-armor"></i>
```

It is possible to use other elements besides `<i>`, however we strongly recommend standardizing
on the use of this element because it is deprecated in HTML5 and unused elsewhere throughout
our standard codebase.

### Icons in Sass

You can add icons to custom classes by either using the `@extend` syntax of Sass:

```scss
.my-custom-class {
  @extend .ico;
  @extend .ico-armor;
}
```

You can also use the bare components to construct a custom class:

```scss
.my-custom-class {
  &::after {
    font-family: 'icons-core';
    display: block;
  }

  &.complete::after {
    content: $ico-enable;
    color: $green-700;
  }

  &.error::after {
    content: $ico-exclamation-triangle;
    color: $red-700;
  }
}
```

## Development

Compilation of the webfont uses [Gulp](https://www.npmjs.com/package/gulp). You can trigger
a Gulp build by running `npm run build`. This will compile the webfont from the source SVG
images.

### Adding New Icons

To add an additional icon, simply add the SVG image to the module directory of the module
to which you want to add the icon. The image name will be used as the CSS class name, so
the filename should follow our CSS class naming convention (e.g. kebab-case-image.svg).
Once you've added the new SVG, run `npm run build` again to make sure that it compiles
correctly.

Compilation re-generates and rewrites the HTML, SCSS, and CSS source files. Commit these
files (including newly-added SVG files) back to source control.

Note: Be sure to check for alignment regressions after new builds.

### Adding New Modules

Modules are separate SCSS/CSS payloads that allow a user of the package to import only
subsets of icons that they need without having to facilitate CSS tree-shaking in their
project.

To add a module, add a new directory in [src/icons](src/icons). Similarly to image names,
the module names should also follow our naming convention (kebab-case). You'll also need
to add the new module to [config.json](config.json) in the root of the project.