Icon Engine Guide

This guide explains how the icon engine works in Zova within the Cabloy monorepo.

Why the icon engine exists

In large systems, no fixed built-in icon set is ever enough.

Zova’s icon engine solves that problem by treating icons as a modular, asynchronous, UI-library-independent resource system.

Core advantages

Several important advantages stand out:

• easy icon maintenance
• performance-conscious loading behavior
• asynchronous loading on demand
• UI-library independence

This is especially important for Cabloy because the same icon strategy should work across Basic and Start even when their UI libraries differ.

Basic concepts

The icon engine is organized around two ideas:

Icon group

A group combines multiple SVG icons into one asynchronously loaded unit.

Icon module

An icon module can contain multiple groups, and a system can contain multiple icon modules.

Naming convention

The naming convention is:

{moduleName}:{groupName}:{iconName}

Representative example:

• full name: home-icon:default:add

There are also shorthand rules, such as:

• ::add
• :auth:github
• test-othericon::icon

This matters because icon use is part of the framework’s typed, discoverable resource model.

Access helpers

Two important helpers are:

• icon for typed icon-name access and completion
• iconh for directly generating the icon vnode

UI-library independence

The icon engine exposes a unified interface that can be used from multiple UI libraries.

This is one of the clearest places where Zova’s architecture deliberately protects higher-level app code from UI-library churn.

Create and build icons

A simple process looks like this:

1. initialize the icon skeleton
2. place SVG icons into the module/group directory
3. regenerate metadata

The metadata generation step matters because icons are part of the framework’s typed resource graph.

Implementation checks for icon-related changes

When adding icons, do not hardcode one-off icon usage patterns too quickly.

A better default is to ask:

1. should the icon belong in an existing icon module or a new one?
2. what group should own it?
3. should metadata be regenerated after adding the icon?
4. is the chosen icon usage path still UI-library-independent?

That keeps icon work maintainable and consistent across editions.