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:

npm install -S @gn-as/icons

If you prefer Yarn, use the following command instead:

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:

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

For example, to import the 16x16 search icon:

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:

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:

<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
2. Create a new branch for your work (git checkout -b icon-proposal).
3. Add your new icon(s) to the appropriate src/svg folder(s) (glyphs go at the top-level...not in a size-specific directory)
4. 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.
5. 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.
6. Confirm the project successfully builds by executing npm run build.
7. Commit your changes bundling changes for each specific icon into one commit to simplify the review/approval process.
8. 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.

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 for examples.
2. 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.
2. Create a new merge request with the main as the "Source" branch and release being "Target" branch.
3. Wait for the CI pipeline to succeed.
4. 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.