Writing

Icon naming conventions that survive a redesign

An icon named settings-gear is fine until the settings page uses a slider instead. An icon named gear is still correct, because a gear is still a gear.

That is the whole rule: name the drawing, not the job. Everything below follows from it.

Three name types that go stale

The place name

sidebar-toggle, header-search, checkout-lock. These bind an icon to a location. Locations move. Within a year you have a header-search used in the footer, and nobody trusts the names any more.

The intent name

delete, confirm, danger. These bind an icon to a meaning. Meanings are reassigned faster than locations. The trash can that means delete today means discard draft tomorrow, and the red triangle that means danger becomes needs review.

Intent names also collide. Two designers will both reach for warning, and one of them will get warning-2.

The number name

arrow-1, arrow-2, arrow-3. This is what happens when the first two fail. Nobody can pick from this list without opening every file.

What to use instead

Name the object, in the singular, in lower case, joined by hyphens.

Then put every other word in the keywords, where it belongs. trash-can can carry delete, remove, bin, discard, throw it away, get rid of it. The name stays stable and the search still finds it by intent.

This separation is the point. A name is an identifier. A keyword list is an index. Trying to make one string do both jobs is what produces danger-alert-triangle-warning-icon.

Rules that keep a set consistent

• Singular, always. book, not books. Plurals split the set in two, and nobody remembers which one you chose.
• No type suffix. Every file in the directory is an icon. home-icon.svg says nothing that the directory did not.
• Order from general to specific. arrow-up, arrow-up-right, arrow-circle-up. The set then sorts into families on its own.
• No abbreviations. notification, not notif. You will not remember which words you shortened.
• One word per meaning. Pick trash-can or bin, and use it everywhere. A set that uses both has two names for one idea and will grow a duplicate drawing.

That last one is worth enforcing in the build. A uniqueness check on the normalised name and phrase costs nothing and catches the duplicate on the day somebody adds it.

Handle variants with a suffix, not a new name

A filled version of an outline icon is the same object. Suffix it:

bell
bell-filled
bell-slash
bell-slash-filled

Not notification-active, notification-muted. The suffix pattern sorts together, reads clearly, and does not need a decision each time.

What about a name nobody would search for?

Some objects have an obvious drawing and an unobvious name. A dustpan is one. Nobody types dustpan.

Keep the accurate name and let the keywords carry the search: sweep up, clean the floor, mess, crumbs. This is the case that proves the separation is right. If the name had to be searchable you would call it cleaning, and then you would have nowhere to put the broom.

Our set of 3000 icons follows exactly this rule, with about seventeen keywords for each name.

Questions people ask

Should icon names match the component names?

No. A component is a job, an icon is a drawing. DeleteButton can render trash-can. Keeping them separate means you can change what the button shows without renaming a file.

Is kebab case or camel case better for icon files?

Use kebab case for the files, because file systems differ on case and a lower case name is safe everywhere. Convert to the case your framework wants at build time.

How do I rename icons without breaking every project?

Keep the old name as an alias that resolves to the new one, and record when you will drop it. A rename with no alias is a breaking change, whatever the version number says.

Should the category be part of the name?

No. Put it in the metadata. A category in the name means an icon cannot be recategorised without a rename, and some icons genuinely belong in two places.