@quartzds/icon-generator NPM

@quartzds/icon-generator

Icon library generator for the Quartz design system.

💿 Installation

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 easy 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 tyoes are described in the src/metadata/types.ts file. Here's a minimal example:

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, additional 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
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, as well as Fantasticon's configuration file, are both supported by @quartzds/icon-generator.