SPDX-FileCopyrightText: © 2024 Schneider Electric

SPDX-License-Identifier: Apache-2.0

@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 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:

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

⚖️ License

See the LICENSE file for license rights and limitations.