Your Icon Pipeline Needs a Lockfile

Your JavaScript dependencies are locked.

Your icons probably aren't.

A common icon workflow still looks like this:

search
  ↓
download SVG
  ↓
optimize
  ↓
generate components
  ↓
build

It looks deterministic.

But if the upstream SVG changes, the icon is renamed, the search result changes, or your transformation rules evolve, the same project can generate different assets later.

For a design system or an application using hundreds of icons, that becomes a reproducibility problem.

The missing piece can be a lockfile.

Icons are dependencies too

A project might declare the icons it wants:

{
  "icons": [
    "search",
    "settings",
    "arrow-left"
  ]
}

But this does not tell us exactly which SVG files were selected.

A lockfile could record the resolved asset:

{
  "search": {
    "id": "example-outline:search",
    "license": "MIT",
    "source": "https://example.com/search.svg",
    "sha256": "8f7c..."
  }
}

Now the project knows both:

what we wanted
+
what we actually used

That distinction matters.

Why CI should not fetch the latest SVG

Consider this build:

CI
 ↓
search API
 ↓
download current SVG
 ↓
generate component

Today:

search.svg → hash A

A few months later:

search.svg → hash B

Your application code has not changed.

But your UI may have.

A safer workflow is:

discover
   ↓
select
   ↓
lock
   ↓
build

CI should build from an already resolved asset rather than silently selecting a new one.

What should be locked?

There is no universal SVG lockfile format.

But useful fields include:

icon ID
source set
content hash
license
source URL
source version or revision

If your pipeline transforms SVGs, you may also want:

transform configuration
generator version
output hash

A filename alone is not enough.

arrow-left.svg can keep the same name while its geometry changes.

A content hash lets you detect that.

Icon updates should be explicit

Instead of:

build → fetch latest

prefer:

check
  ↓
review
  ↓
update lockfile
  ↓
commit

If an upstream icon changes, the lockfile diff makes the update visible:

"search": {
-  "sha256": "91cc..."
+  "sha256": "ba72..."
}

You can then review the visual result before accepting it.

A hash tells you that something changed.

A visual diff tells you whether the change matters.

Keep provenance with the asset

Icons often come from different open-source sets and licenses.

The resolved record can preserve that context:

{
  "id": "example:calendar",
  "set": "Example Icons",
  "license": "MIT",
  "source": "https://...",
  "hash": "sha256:..."
}

This does not replace reading the license.

But it makes future auditing much easier.

It also helps when an icon is renamed or removed upstream: your existing build can continue using the locked asset until you deliberately choose a replacement.

Coding agents make this even more useful

Suppose an agent receives:

Add a settings icon to this toolbar.

Without constraints, it may search the current catalog and choose a new icon every time.

A stronger workflow is:

request concept
   ↓
check locked icons
   ↓
reuse existing asset
   ↓
propose a new one only if needed
   ↓
review
   ↓
update lockfile

Discovery stays flexible.

Adoption becomes explicit.

Discovery and reproducibility are different problems

An icon search engine answers:

Which icon could I use?

A lockfile answers:

Which exact icon did we decide to use?

For example, a team can use SVGicons.com to discover open-source icons across multiple sets while comparing source and license information.

Once an icon is adopted, the project should be able to preserve that exact decision.

A useful model is:

DISCOVER
   ↓
SELECT
   ↓
LOCK
   ↓
BUILD

Search can change.

Production builds should not.

Final checklist

Ask yourself:

• Can we rebuild the same icons six months from now?
• Can we detect an upstream SVG change?
• Are source and license metadata preserved?
• Are icon updates explicit and reviewable?
• Can CI build without rediscovering assets?
• Can a coding agent reuse existing icon decisions?

If several answers are no, your icon pipeline may already have dependencies.

It just doesn't have a lockfile for them yet.