npm package: @gn-as/icons
Description: Icons for digital and software products using the Gina, the GN Advanced Science Design System
Latest version: 1.4.5

# Overview

This is a repository of icons for digital and software products using the Gina Design System.

# Getting started

To install `@gn-as/icons` in your project, you will need to run the following
command using [npm](https://www.npmjs.com/):

```bash
npm install -S @gn-as/icons
```

If you prefer [Yarn](https://yarnpkg.com/en/), use the following command
instead:

```bash
yarn add @gn-as/icons
```

# Usage

## Framework-specific packages

The following packages provide APIs that feel more "natural" in the context of
the associated framework and are recommended when working in projects using the
associated framework.

|Framework                |Package               |
|-------------------------|----------------------|
|Svelte                   |[@gn-as/icons-svelte] |

Adding framework-specific packages is not difficult. If you are using a
framework that is not listed above and would like a new package created, [create
an issue] and the project Maintainers work with you to get it added.

## Vanilla JavaScript

Once you've found an icon and you're looking to use it in Vanilla JavaScript,
you can import the icon by writing the following in your JavaScript file:

```js
import IconName from '@gn-as/icons/<module-type>/path-to-icon/size';
```

For example, to import the 16x16 `search` icon:

```js
import Search from '@gn-as/icons/es/search/16';
```

Use `es` for ES2015 modules (ESM), but one may also use `lib` for CommonJS or
`umd` for UMD modules.

Use the [`carbon/icon-helpers` package] to render the icon to the screen. This
package gives two options for rendering icons: `toString` and `toSVG`. If
rendering in templates, you may want to use the former. If rendering to the DOM,
`toSVG` may be helpful.

Here's an example of using `toSVG` to create a node in the DOM for the 16x16 `add`
icon:

```js
import { getAttributes, toSVG, toString } from '@carbon/icon-helpers';
import searchIcon from '@gn-as/icons/es/search/16';

// Creates an SVG _node_ that can be added to the DOM
const iconNode = toSVG({
  ...searchIcon,
  attrs: getAttributes(searchIcon.attrs),
});

// Creates a string containing the actual SVG markup as a string
const svgString = toString({
  ...searchIcon,
  attrs: getAttributes(searchIcon.attrs),
});
```

## Svelte

If you are developing a Svelte app, we recommend you use the
[@gn-as/icons-svelte] package. However, you _could_ insert an icon into your
page with this library like this:

```html
<script>
  import { getAttributes, toString } from '@carbon/icon-helpers';
  import appsIcon from '@gn-as/icons/lib/apps/32'; // note size is chosen by import

  const markup = toString({ ...appsIcon, attrs: getAttributes(appsIcon.attrs) });
</script>

{@html markup}
```

# Contributing

## I have an icon I want to add...

### I have NodeJS/NPM installed

1. Clone the repository
1. Create a new branch for your work (`git checkout -b icon-proposal`).
1. Add your new icon(s) to the appropriate `src/svg` folder(s) (glyphs go at the top-level...not in a size-specific directory)
1. Update the [`icons.yml`](icons.yml) file with metadata for the icon(s) you've
    added. You must include values for `name`, `friendly_name`, and `sizes`, other
    values are optional.
1. Update the [`categories.yml`](categories.yml) file with the categories the
    icon should be associated with. If you feel a new category is appropriate, feel
    free to add it and it will be reviewed.
1. Confirm the project successfully builds by executing `npm run build`.
1. Commit your changes bundling changes for each specific icon into one commit
    to simplify the review/approval process.
1. Submit a [Merge Request](https://docs.gitlab.com/ee/user/project/merge_requests/getting_started.html).

The project maintainers will be notified and will either merge the icon or be in
touch with feedback regarding the proposal.

### I don't know what NodeJS/NPM are (or they aren't installed)

1. Create the icon you are proposing (in 16, 20, 24, or 32 pixel squares). _Note: See [design/ui-icon-master.ai](./design/ui-icon-master.ai) for examples._
1. [Create an issue] and attach the proposed icon. The project maintainers will be notified and
    will work with you to find a satisfactory icon.

## I need an icon that is not present, but do not have a design in mind

Sometimes you need an icon for something but don't know where to start on the
design...you just know the _intent_ it must convey ("filtering", "search", etc).
In this case, just [create an issue] and explain what your needs. The project
maintainers will be notified and will work with you to find a satisfactory icon.

# Releasing

The overall release process is the same:

1. Make changes and commit following the [Conventional Commits specification].
1. Create a new merge request with the `main` as the "Source" branch and
   `release` being "Target" branch.
1. Wait for the CI pipeline to succeed.
1. Merge.

This publishes a new tagged release and NPM package automatically via the CI
pipeline.

# Reference

This library is derived from the [Carbon Design System's Icons
repository/package] but tailored to the needs of the GN Advanced Science team.

Special thanks to IBM and the team behind the Carbon Design System and
associated repositories. If you are looking for a more robust design system, we
recommend checking Carbon out!

# 📝 License

Licensed under the [Apache 2.0 License](/LICENSE).

[Carbon Design System's Icons repository/package]: https://github.com/carbon-design-system/carbon/tree/main/packages/icons
[`carbon/icon-helpers` package]: https://github.com/carbon-design-system/carbon/tree/main/packages/icon-helpers
[create an issue]: https://gitlab.com/gn-as/ecosystem/platform/resops/gina/icons/-/issues/new
[@gn-as/icons-svelte]: https://gitlab.com/gn-as/ecosystem/platform/resops/gina/icons-svelte
[conventional commits specification]: https://www.conventionalcommits.org/en/v1.0.0/#summary