SVG Icon Generation and Maintenance Mechanism

1. Purpose

This document describes the recommended mechanism for maintaining SVG icons in the Angular application.

The application uses dedicated Angular components to render icons. Each generated icon component contains an inline SVG template. The list of available icons is maintained in a central registry called ICON_REGISTRY.

The goal of this mechanism is to make icon maintenance predictable, repeatable, and safe:

• analysts or designers can review and update SVG assets as regular files;

• developers do not manually edit generated Angular icon components;

• generated icon components and ICON_REGISTRY are always synchronized;

• monochrome icons support application-level size and color control;

• multicolor icons can preserve their original colors;

• icon names remain stable and meaningful across the application.

2. Scope

This mechanism covers:

• storing source SVG files in a dedicated project folder;

• sharing SVG files with analysts or designers;

• updating existing SVG icons;

• adding new SVG icons;

• removing obsolete SVG icons;

• generating Angular icon components;

• regenerating the central icon registry;

• normalizing SVG size attributes;

• handling monochrome and multicolor SVG files.

This mechanism does not cover:

• runtime loading of SVG files from the assets folder;

• dynamic icon loading from a backend service;

• manual editing of generated icon component files;

• automatic design approval of SVG content.

3. Current Icon Architecture

The application uses a component-based icon system.

Each icon is represented by a dedicated Angular standalone component.

Example structure:

The file icons.ts contains the global registry of available icons and their names.

Conceptually:

A common icon host component can use this registry to resolve and render the required icon by name.

Example usage:

4. Target Process Overview

The project should contain a dedicated SVG source folder.

Recommended folder:

This folder is the source of truth for SVG icon files.

The generation script reads SVG files from this folder, removes previously generated icon components, creates new Angular components, and rebuilds ICON_REGISTRY.

High-level process:

1. The developer provides the current SVG set to an analyst or designer.

2. The analyst or designer reviews, modifies, adds, or removes SVG files.

3. The developer places the approved SVG files into icons-source/.

4. The developer runs the icon generation script.

5. The script regenerates Angular components and the icon registry.

6. The developer reviews generated changes and commits them.

5. Roles and Responsibilities

6. Recommended Directory Structure

7. Source Folder

7.1 Folder Location

The recommended folder is:

This folder should be located outside the Angular src/assets directory.

It should not be referenced by the Angular build configuration as an application asset.

The folder is used only by the generation script.

7.2 Source Folder Purpose

The icons-source/ folder is used for:

• storing source SVG files;

• exchanging icons between developers and analysts or designers;

• maintaining stable icon names;

• regenerating Angular icon components;

• ensuring that the generated icon registry reflects the current SVG set.

The folder should be treated as the source of truth.

Generated Angular component files should be treated as derived artifacts.

8. Naming Rules

8.1 General Naming Rule

The SVG file name defines the icon name.

Recommended file naming convention:

Examples:

Recommended registry key convention:

This keeps icon usage natural in TypeScript and Angular templates.

Example:

8.2 Allowed File Name Pattern

Recommended file name pattern:

Valid examples:

Discouraged examples:

Reasons:

• spaces may cause scripting and tooling issues;

• uppercase names create inconsistent generated code;

• underscores make the convention less predictable if kebab-case is expected;

• the icon- prefix duplicates the generated component folder prefix;

• temporary names such as final-v2 are unclear and tend to become permanent.

8.3 Multicolor Icon Naming

Multicolor icons must use the .color.svg suffix.

Examples:

The .color marker means:

• original SVG colors must be preserved;

• automatic monochrome color replacement must not be applied;

• size normalization still applies.

The generated registry key ignores the .color suffix.

Examples:

9. SVG Normalization Rules

The generation script must normalize SVG files before writing them into Angular templates.

9.1 Size Normalization

All generated SVG templates should use CSS-controlled icon sizing.

The root svg element should contain:

Example generated SVG:

This allows the icon size to be controlled with CSS.

Example:

9.2 ViewBox Preservation

The generation script must preserve the original viewBox.

Example:

The viewBox defines the SVG coordinate system and is required for correct scaling.

The script should not remove or recalculate viewBox unless a separate SVG optimization step is explicitly introduced and documented.

9.3 Width and Height Replacement

If the source SVG contains fixed dimensions, they must be replaced.

Source:

Generated:

The purpose is to avoid hardcoded icon dimensions in generated Angular templates.

9.4 XML Header and DOCTYPE Removal

The script may remove XML declarations and document type declarations.

Source:

Generated:

Inline SVG inside Angular templates does not require XML headers.

10. Color Handling

Color handling is the most important part of the mechanism.

There are two supported icon types:

1. monochrome icons;

2. multicolor icons.

10.1 Monochrome Icons

Monochrome icons are regular SVG files without the .color.svg suffix.

Examples:

For monochrome icons, the generation script should replace black fill and stroke values with:

This allows icons to follow the application theme.

Source SVG:

Generated SVG:

The icon color can then be controlled with CSS.

Example:

10.2 Supported Monochrome Color Replacements

The script should replace common black color formats.

Recommended replacement list:

Properties to process:

Supported forms:

10.3 Values That Must Not Be Replaced

The script must not replace structural or special SVG values.

Examples:

Examples:

fill="none" must remain unchanged because it is a structural SVG instruction, not a visible color.

10.4 Multicolor Icons

Multicolor icons must be named with the .color.svg suffix.

Examples:

For these files, the generation script must preserve original colors.

Source:

Generated:

Only size normalization is applied.

10.5 Why Explicit Multicolor Marking Is Required

Automatic multicolor detection is risky.

Example:

This may represent:

• a monochrome icon exported with slightly different shades;

• a deliberately multicolor icon;

• an export artifact from a design tool.

The generator should avoid guessing design intent.

Therefore, .color.svg is used as an explicit and predictable marker.

11. Generated Angular Component Rules

For each source SVG file, the script generates one Angular standalone component.

Example source file:

Generated folder:

Generated files:

11.1 Generated HTML Template

The generated .html file contains the normalized inline SVG.

Example:

11.2 Generated TypeScript Component

The generated .ts file contains a minimal Angular standalone component.

Example:

11.3 Generated Component Naming

12. Generated Registry Rules

The script regenerates the registry file:

The file should contain:

• imports for all generated icon components;

• the ICON_REGISTRY object;

• optionally, a generated union type for available icon names.

Recommended generated structure:

Using as const allows TypeScript to infer a strict list of available icon names.

13. Runtime Usage

A generic icon component can accept an icon name and render the corresponding generated component dynamically.

Example:

CSS variables control icon size and color.

Example:

For multicolor icons, --icon-color is not expected to affect internal SVG colors.

14. Developer Workflow

14.1 Updating Existing Icons

14.2 Adding a New Icon

14.3 Replacing the Full Icon Set

15. Generation Algorithm

The script should follow this algorithm.

16. Component Generation Mapping

17. Color Handling Decision Tree

18. Build Integration

The icon generation script can be run manually or integrated into package scripts.

Recommended command:

Manual execution:

Optional CI validation command:

If generated files are outdated, the CI job fails because git diff --exit-code detects changes.

19. Pull Request Checklist

Before merging icon changes, reviewers should verify:

• [ ] SVG files are placed in icons-source/.

• [ ] File names follow the naming convention.

• [ ] Multicolor icons use the .color.svg suffix.

• [ ] Generated components were updated.

• [ ] ICON_REGISTRY was regenerated.

• [ ] IconRegistryKey was regenerated.

• [ ] No manual edits were made inside generated icon components.

• [ ] The application builds successfully.

• [ ] Icons are visually checked in relevant UI screens.

• [ ] No unexpected hardcoded dimensions remain in generated SVG files.

• [ ] Monochrome icons use var(--icon-color, var(--clr-accent-6)).

20. Validation Rules

The generation script should validate SVG files before generation.

21. Handling Potential Issues

21.1 Missing ViewBox

Problem:

Without viewBox, scaling may be incorrect.

Recommended action:

• ask the analyst or designer to export SVG with viewBox;

• or manually fix the source SVG before generation.

The generator may stop with an error if viewBox is missing.

21.2 Incorrect Multicolor Icon Processing

Problem:

A multicolor logo was named:

As a result, black paths may be replaced with the theme color.

Correct file name:

Then rerun:

21.3 Icon Color Does Not Change in UI

Possible reasons:

1. The source SVG was marked as multicolor by using .color.svg.

2. The SVG uses a color value that is not included in the replacement list.

3. The SVG uses gradients, masks, or embedded styles.

4. CSS variable --icon-color is not set in the expected scope.

Recommended check:

If the icon color changes, the generation worked correctly.

21.4 Icon Size Does Not Change in UI

Possible reasons:

1. The generated SVG still contains fixed dimensions.

2. CSS variable --icon-size is not set.

3. Parent layout restricts icon dimensions.

Recommended check:

22. Generated Files Policy

Generated files should not be edited manually.

This includes:

Any changes to generated files must be made by updating SVG files in:

and rerunning:

Manual edits are likely to be overwritten by the next generation.

23. Recommended README for icons-source

The following README.md may be placed into the source folder.

24. Recommended Script Behavior Summary

The generator should:

1. read SVG files from icons-source/;

2. validate file names;

3. detect multicolor icons by .color.svg;

4. remove old generated components;

5. normalize SVG size attributes;

6. preserve viewBox;

7. replace black colors for monochrome icons;

8. preserve colors for multicolor icons;

9. create one Angular component per icon;

10. regenerate ICON_REGISTRY;

11. print a summary.

25. End-to-End Process

26. Key Design Decisions

27. Recommended Future Improvements

Possible future improvements:

• add SVG optimization with SVGO;

• add a dry-run mode;

• add a validation-only mode for CI;

• generate an icon catalog page for QA and analysts;

• add visual regression tests for icon changes;

• add a reverse export script if generated components must be converted back to SVG files.

28. Glossary