DEV Community

Cover image for One Icon Catalog, Many Delivery Surfaces
Svg/icons
Svg/icons

Posted on

One Icon Catalog, Many Delivery Surfaces

#webdev #systemdesign #svg #devtools

An icon system can have many versions.

Your React package may be 3.4.1.

Your Vue package may be 2.8.0.

Your CLI may be 1.6.2.

That is not a problem.

The problem starts when they no longer expose the same icon catalog.

Package version and catalog version are different things

Software packages evolve for many reasons:

  • bug fixes
  • framework compatibility
  • build changes
  • new commands
  • performance improvements

None of these necessarily changes the icons themselves.

So package versions alone cannot tell you which icon catalog a tool is using.

A better model is:

React package   3.4.1  → Catalog 42
Vue package     2.8.0  → Catalog 42
CLI             1.6.2  → Catalog 42
API                    → Catalog 42
MCP server             → Catalog 42
Enter fullscreen mode Exit fullscreen mode

Different software versions.

Same catalog state.

Drift is easy to introduce

Now imagine this:

Website         → Catalog 42
React           → Catalog 42
Vue             → Catalog 42
API             → Catalog 41
CLI             → Catalog 39
MCP             → Catalog 42
Enter fullscreen mode Exit fullscreen mode

Everything may still appear to work.

Until someone asks for an icon that was introduced in catalog 42.

The website finds it.

React finds it.

The API does not.

The CLI returns nothing.

This is not really a package problem.

It is catalog drift.

The SVG is only part of the catalog

Keeping the same SVG file everywhere is not enough.

An icon catalog also contains things like:

name
aliases
tags
category
family
style
deprecation status
metadata
SVG data
Enter fullscreen mode Exit fullscreen mode

Suppose an icon changes from:

arrow-next
Enter fullscreen mode Exit fullscreen mode

to:

arrow-right
Enter fullscreen mode Exit fullscreen mode

The geometry may remain identical.

But if the API knows the new name while the CLI still exposes the old one, the two surfaces have already diverged.

For developers, metadata drift can be just as disruptive as SVG drift.

Give the catalog its own identity

One useful approach is to make every generated catalog identifiable.

For example:

{
  "catalogVersion": 42,
  "catalogHash": "9c84f2...",
  "generatedAt": "2026-09-23T14:20:00Z"
}
Enter fullscreen mode Exit fullscreen mode

Every delivery surface can expose this information.

Then checking synchronization becomes trivial:

Website   42 / 9c84f2 ✓
React     42 / 9c84f2 ✓
Vue       42 / 9c84f2 ✓
API       42 / 9c84f2 ✓
CLI       42 / 9c84f2 ✓
MCP       42 / 9c84f2 ✓
Enter fullscreen mode Exit fullscreen mode

And drift becomes immediately visible:

API       41 / 71aa03 ✗
Enter fullscreen mode Exit fullscreen mode

Generate from a snapshot

Instead of letting each integration build its own interpretation of the library, generate them from a defined catalog snapshot.

Conceptually:

                  CATALOG SNAPSHOT 42
                         │
        ┌────────────────┼────────────────┐
        │                │                │
      Website          React            Vue
        │
       API              CLI              MCP
Enter fullscreen mode Exit fullscreen mode

The important part is not that every output is built with the same technology.

It is that every output starts from the same catalog state.

This matters even more when machines consume the library

For a human browsing icons, a synchronization problem may be annoying.

For software, it can become a contract problem.

Imagine an automated workflow doing this:

1. Search for "database"
2. Select icon "database-cloud"
3. Request its SVG through an API
4. Export it through a CLI
Enter fullscreen mode Exit fullscreen mode

If search, API and CLI are not based on the same catalog revision, the workflow becomes unpredictable.

The same is true for tools used by AI agents.

Once an agent can search, inspect and retrieve icons programmatically, consistency between surfaces becomes part of the API contract.

Releases do not have to happen together

This does not mean every integration needs to ship simultaneously.

A React package may require a release while the API does not.

A CLI may receive a bug fix without changing the catalog.

Their release cycles can remain independent.

The important distinction is:

software version ≠ catalog version
Enter fullscreen mode Exit fullscreen mode

Two completely different package versions can still expose exactly the same catalog.

A small piece of metadata can prevent a lot of confusion

For any system distributing the same assets through multiple channels, exposing three values can already help:

catalogVersion
catalogHash
generatedAt
Enter fullscreen mode Exit fullscreen mode

They make it possible to answer a surprisingly important question:

Are these two tools actually talking about the same set of icons?

As an icon library grows from files into infrastructure, that question becomes increasingly important.

Different tools can have different versions.

They just should not have different versions of the truth.

Top comments (0)