<commit_before>## Building an Icon Library

<!-- prettier-ignore-start -->
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
## Table of Contents

- [Introduction](#introduction)
- [Getting Started](#getting-started)
  - [Philosophy](#philosophy)
  - [Project structure](#project-structure)
    - [`package.json` scripts](#packagejson-scripts)
    - [Breaking down `tasks/build.js`](#breaking-down-tasksbuildjs)
    - [Understanding `@carbon/icon-helpers`](#understanding-carbonicon-helpers)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->
<!-- prettier-ignore-end -->

## Introduction

So you want to build an icon library for your favorite framework? That's
awesome! We're so happy to hear that 🎉 We hope that this guide can serve as a
reference to help get you up-and-running quickly so you can start using these
icons as quickly as possible.

However, before getting started, make sure that you have
[created an issue](https://github.com/IBM/carbon-elements/issues/new?labels=&template=feature_request.md)
on the Carbon Elements project and have received a green light from one of the
core contributors. This is in order to verify that the work is going to the
right place in the Carbon Elements ecosystem.

After you've received the green light, then you're ready to get started!

## Getting Started

The main package that exports all icon information is
[`@carbon/icons`](/packages/icons). This package contains all of the source SVG
assets, in addition to exporting the following assets:

- Optimized SVG assets from source files
- Icon descriptors that encode SVG information in JavaScript
- A `meta.json` file useful for individuals like yourself building an icon
  library!

If you're curious about `@carbon/icons` and want to learn more, definitely check
out our [Icon documentation](/docs/icons.md)!

### Philosophy

At a high-level, each icon library should have the following design goals when
determining how to best architect their implementation:

- Given the size of the IBM Design Language icon set, each library should aim to
  support both direct imports and a tree-shakeable entrypoint
  - Direct path: `/es/icon-name/16.js`
  - Entrypoint: `/es/index.js`
  - In general, this means that we cannot support a generic
    `<Icon name="icon-name">` component given that we could not tree-shake
    `@carbon/icons` descriptors
  - A system could support `<Icon icon={descriptor} />`, however this would
    require a user to install two dependencies versus only your icon library
- Minimize the amount of runtime logic that has to be run. As a result, prefer
  generating markup statically from SVG data versus using the data at runtime to
  build up the SVG markup
- Verify that your `<svg>` containers have the right attributes by using the
  `@carbon/icon-helpers` package. This includes a helper called `getAttributes`
  that will provide the proper attributes to apply on the `<svg>` container
- Make sure that the import paths of your icons are consistent with the
  `@carbon/icons` package. This information is made available through
  `@carbon/icons/meta.json`
  - In other words, don't create ad-hoc direct import paths. We should try and
    stay consistent across packages

### Project structure

After following our [contribution guidelines](/.github/CONTRIBUTING.md), you<commit_msg>docs: update icon documentation link (#7107)<commit_after>## Building an Icon Library

<!-- prettier-ignore-start -->
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
## Table of Contents

- [Introduction](#introduction)
- [Getting Started](#getting-started)
  - [Philosophy](#philosophy)
  - [Project structure](#project-structure)
    - [`package.json` scripts](#packagejson-scripts)
    - [Breaking down `tasks/build.js`](#breaking-down-tasksbuildjs)
    - [Understanding `@carbon/icon-helpers`](#understanding-carbonicon-helpers)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->
<!-- prettier-ignore-end -->

## Introduction

So you want to build an icon library for your favorite framework? That's
awesome! We're so happy to hear that 🎉 We hope that this guide can serve as a
reference to help get you up-and-running quickly so you can start using these
icons as quickly as possible.

However, before getting started, make sure that you have
[created an issue](https://github.com/IBM/carbon-elements/issues/new?labels=&template=feature_request.md)
on the Carbon Elements project and have received a green light from one of the
core contributors. This is in order to verify that the work is going to the
right place in the Carbon Elements ecosystem.

After you've received the green light, then you're ready to get started!

## Getting Started

The main package that exports all icon information is
[`@carbon/icons`](/packages/icons). This package contains all of the source SVG
assets, in addition to exporting the following assets:

- Optimized SVG assets from source files
- Icon descriptors that encode SVG information in JavaScript
- A `meta.json` file useful for individuals like yourself building an icon
  library!

If you're curious about `@carbon/icons` and want to learn more, definitely check
out our [Icon documentation](/docs/guides/icons.md)!

### Philosophy

At a high-level, each icon library should have the following design goals when
determining how to best architect their implementation:

- Given the size of the IBM Design Language icon set, each library should aim to
  support both direct imports and a tree-shakeable entrypoint
  - Direct path: `/es/icon-name/16.js`
  - Entrypoint: `/es/index.js`
  - In general, this means that we cannot support a generic
    `<Icon name="icon-name">` component given that we could not tree-shake
    `@carbon/icons` descriptors
  - A system could support `<Icon icon={descriptor} />`, however this would
    require a user to install two dependencies versus only your icon library
- Minimize the amount of runtime logic that has to be run. As a result, prefer
  generating markup statically from SVG data versus using the data at runtime to
  build up the SVG markup
- Verify that your `<svg>` containers have the right attributes by using the
  `@carbon/icon-helpers` package. This includes a helper called `getAttributes`
  that will provide the proper attributes to apply on the `<svg>` container
- Make sure that the import paths of your icons are consistent with the
  `@carbon/icons` package. This information is made available through
  `@carbon/icons/meta.json`
  - In other words, don't create ad-hoc direct import paths. We should try and
    stay consistent across packages

### Project structure

After following our [contribution guidelines](/.github/CONTRIBUTING.md), you
{'fraction_non_alphanumeric': 0.0818418013856813, 'fraction_numerical': 0.0011547344110854503, 'mean_word_length': 4.261199696279423, 'pattern_counts': {'":': 0, '<': 21, '<?xml version=': 0, '>': 21, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3298318', 'n_tokens_mistral': 1876, 'n_tokens_neox': 1763, 'n_words': 884}