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:

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

If you prefer Yarn, 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//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


{@html markup}
`

Contributing

I have an icon I want to add...

$3

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

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

$3

1. Create the icon you are proposing (in 16, 20, 24, or 32 pixel squares). _Note: See 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.

[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