npm package: @quartzds/icon-generator
Description: Quartz design system icon generator
Latest version: 10.3.1

---
SPDX-FileCopyrightText: © 2025 Schneider Electric

SPDX-License-Identifier: Apache-2.0
---

# @quartzds/icon-generator

[![NPM Package][npm-badge]][npm-link] [![CI Status][ci-badge]][ci-status]
[![REUSE status][reuse-badge]][reuse-status]
[![License][license-badge]][license]

Icon library generator for the [Quartz design system][quartz].

## 💿 Installation

```bash
npm install --save-dev @quartzds/icon-generator
```

## 📖 Usage

The `qds-icon-generator` reads library YAML metadata and source SVG files to
generate the following assets:

- processed library metadata in `icons.json`
- optimized SVG files including copyright and license headers
- icon fonts with a codepoints JSON file and a CSS file for HTML consumption

Run `qds-icon-generator` alone to display the list of supported commands and
options.

## ⚙️ Commands summary

- `generate-metadata`: read library metadata a YAML file, process it (see below)
  and output the result to a JSON file
- `check-consistency`: check that SVG files in input folder match the list of
  icons defined in the library metadata YAML file
- `generate-svg`: generate optimized SVG files from input files, including
  copyright and license from library metadata
- `generate-font`: generate icon font files from the SVG files

## 📚 Library metadata

The library metadata is a YAML file primarily organizing icons in a hierarchy:

> Library > Categories > Groups > Icons

It also stores important information like copyright, license, guidelines,
generation options, etc.

Note that custom data in the YAML file is preserved in the output JSON file.

### Basic structure

Metadata types are described in the `src/metadata/types.ts` file. Here's a
minimal example:

```yaml
name: Icon library name
brand: Brand name
copyright: © <YEAR> Company name # Library copyright
license: LicenseRef-Proprietary # Library license (SPDX identifier)

categories:
  - name: Category name
    description: Category description

    groups:
      - name: Group name
        description: Group description
        icons:
          - name: Icon name
            tags: [list, of, tags, or, aliases]
```

### Cascading metadata

On top of the basic structure, extended data can be defined at any level of the
hierarchy, defined by the `CascadingMetadata` type.

Metadata will _cascade_ to the descendants of the node on which they're defined.
Descendants can also specify the same metadata again, which will **override
values** inherited from their parent.

There's an exception, though. The `guidelines` will **concatenate** instead of
overriding.

Here's the list of the cascading metadata:

| Name           | Type               | Redefinition behavior             | Description                                                                                                            |
| -------------- | ------------------ | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `copyright`    | string             | Override inherited ancestor value | Copyright statement                                                                                                    |
| `license`      | string             | Override inherited ancestor value | [SPDX license identifier](https://spdx.org/licenses/)                                                                  |
| preserveColors | boolean            | Override inherited ancestor value | Keep colors specified in the source SVG files. `false` by default, which means colors are removed from the source SVG. |
| guidelines     | string \| string[] | Concatenate with ancestor values  | Single guideline, or list of guidelines.                                                                               |

### Additional processing logic

In addition to the cascading feature, the following processing is run:

- _Groups_ are sorted alphabetically within their _Category_
- _Icons_ are sorted alphabetically within their _Group_

Note that the top-level list of _categories_ is not sorted alphabetically.

## 🔧 Alternate configuration

`@quartzds/icon-generator` uses [SVGO][] and [Fantasticon][] to generate icons.
[SVGO's configuration file][svgo-config], as well as [Fantasticon's
configuration file][fantasticon-config], are both supported by
`@quartzds/icon-generator`.

## ⚖️ License

See the [LICENSE](./LICENSE) file for license rights and limitations.

[npm-badge]: https://img.shields.io/npm/v/@quartzds/icon-generator?logo=npm
[npm-link]: https://www.npmjs.com/package/@quartzds/icon-generator
[ci-badge]:
  https://github.com/quartzds/icon-generator/actions/workflows/ci.yml/badge.svg
[ci-status]: https://github.com/quartzds/icon-generator/actions/workflows/ci.yml
[reuse-badge]:
  https://api.reuse.software/badge/github.com/quartzds/icon-generator
[reuse-status]:
  https://api.reuse.software/info/github.com/quartzds/icon-generator
[license-badge]:
  https://img.shields.io/npm/l/@quartzds/icon-generator?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCI+PHBhdGggZD0ibTIzLjkgOS43LTMuNTQtNy44OS0uMDA1LS4wMWEuNTQyLjU0MiAwIDAgMC0uMDQxLS4wNzZsLS4wMTQtLjAxOGEuNTMzLjUzMyAwIDAgMC0uMTIyLS4xMjJsLS4wMTUtLjAxMWEuNTI4LjUyOCAwIDAgMC0uMDgtLjA0NGwtLjAyNC0uMDA5YS41MjcuNTI3IDAgMCAwLS4wNjctLjAybC0uMDI4LS4wMDdhLjUyNC41MjQgMCAwIDAtLjA5Ni0uMDFoLTYuODVjLTEuMDItMS41Mi0xLjAyLTEuNTQtMiAwaC02Ljg2YS41NDMuNTQzIDAgMCAwLS4wOTYuMDFsLS4wMjguMDA3YS41MTYuNTE2IDAgMCAwLS4wNjcuMDJsLS4wMjQuMDFhLjUzNy41MzcgMCAwIDAtLjA4LjA0M2wtLjAxNS4wMTFhLjUxLjUxIDAgMCAwLS4wNTcuMDQ3bC0uMDIuMDJhLjU0My41NDMgMCAwIDAtLjA0NS4wNTVsLS4wMTQuMDE4YS41MjIuNTIyIDAgMCAwLS4wNDEuMDc1bC0uMDA1LjAxdi4wMDFMLjExNiA5LjcyYS41MzEuNTMxIDAgMCAwLS4wOTYuMzA0YzAgMi4yOCAxLjg2IDQuMTQgNC4xNCA0LjE0czQuMTQtMS44NiA0LjE0LTQuMTRhLjUzLjUzIDAgMCAwLS4wOTYtLjMwNGwtMy4yNS02LjM3IDYuMDctLjAyM3YxOC4yYy0yLjU1LjI5NC03LjAxLjM4MS03IDIuNWgxNmMwLTIuMDMtNC40OC0yLjI3LTctMi41di0xOC4xbDUuNjktLjAyLTIuOTIgNi40OWMwIC4wMDIgMCAuMDAzLS4wMDIuMDA1bC0uMDA2LjAxOGEuNTQ1LjU0NSAwIDAgMC0uMDIzLjA3NWwtLjAwNS4wMmEuNTI0LjUyNCAwIDAgMC0uMDEuMDkydi4wMDhjMCAyLjI4IDEuODYgNC4xNCA0LjE0IDQuMTQgMi4yOCAwIDQuMTQtMS44NiA0LjE0LTQuMTRhLjUyOC41MjggMCAwIDAtLjEyLS4zMzJ6IiBmaWxsPSIjZmZmIj48L3BhdGg+PC9zdmc+
[license]: ./LICENSE
[quartz]: https://github.com/quartzds
[svgo]: https://github.com/svg/svgo
[fantasticon]: https://github.com/tancredi/fantasticon
[svgo-config]: https://github.com/svg/svgo#configuration
[fantasticon-config]: https://github.com/tancredi/fantasticon#configuration-file