An icon library with 124k files is only useful if people can find the right file. Good naming and search metadata are the difference between a 10-second lookup and a browsing session that ends in frustration. These are the rules that scale.

Start with a stable id convention

Every icon needs one immutable id used by URLs, filenames and component names. Lowercase kebab-case is the safest convention because it works across Linux, Windows, npm and web URLs without escaping problems:

chat-bubble
arrow-circle-down
file-pdf
user-add

Keep the id stable forever. Renaming an icon breaks links, saved favorites, imports and search history. If the artwork changes, keep the id and bump the artwork version; if you must rename, ship redirects and aliases.

Write a display name humans read

The file id is for machines; the display name is for humans. "chat-bubble" becomes "Chat bubble", "user-add" becomes "Add user". Search should match both the technical id and the natural-language name, because developers remember the id while designers remember what they called it in a wireframe.

Treat tags as search aliases

Tags are not decoration. They are the synonyms that rescue a search. For a calendar icon, useful tags include `date`, `schedule`, `event`, `month`, `appointment` and `planner`. Generate them from real queries, not from the same words already in the id:

{
  "id": "calendar",
  "name": "Calendar",
  "category": "object",
  "tags": ["calendar", "date", "schedule", "event", "month", "appointment"]
}

Misspellings and regional terms matter too. An American and a British team may search "trash" and "bin" for the same icon. Both should resolve.

Use categories as a first filter, not a final answer

Categories work well for browsing: people click "arrows" or "faces" when they are exploring. They work poorly as the only search mechanism because one icon can belong to several contexts. Keep categories broad and stable, and layer tags on top for precision.

Category names should use the same word a user would say. "Communication" is a useful bucket; "comm" is not. When a library has hundreds of categories, sort them by icon count so empty or near-empty categories do not bury the useful ones.

Make search forgiving

Real searches contain typos, plural forms, abbreviations and fuzzy memories. A good icon search handles at least these cases:

  • Partial words: "trash" matches "trash-bin" and "trashcan".
  • Stemming: "shopping" matches "shop" and "shopping-cart".
  • Acronyms: "pdf" matches "file-pdf" and "document-pdf".
  • Spelling variants: "favourite" matches "favorite".
  • Category names: a search for "arrows" returns icons from the arrows category even if the id says otherwise.

On a client-side icon site, keep the index compact: id, name, category and tags for every icon, then match against a normalized lowercase haystack. The Sendafun search index does exactly that so the full 124k library filters in the browser without server round trips.

Name for component generation

Naming also feeds code generation. A consistent kebab-case id converts cleanly to a PascalCase component name: `arrow-circle-down` becomes `ArrowCircleDown`, and `file-pdf` becomes `FilePdf`. Avoid ids that start with digits, contain spaces, or use reserved words, because each one forces a special case in the generator.

Keep an alias map for migration

Large design systems accumulate legacy names. Keep a small alias table that maps old ids to current ids, and use it in search, MCP lookups and deprecation warnings:

{
  "aliases": {
    "checkmark": "check-circle",
    "save": "floppy-disk",
    "email": "mail"
  }
}

Aliases preserve muscle memory. A developer who has typed `Icon("save")` for three years does not need to learn a new name the day the system rebrands.

Measure what matters

Track the queries that return zero results, because every one is a naming or tagging gap. If "wifi" finds nothing, either the icon is missing or the tags are wrong. Fixing that loop is how a large library stays easy to search as it grows past 100k icons.