A shared icon library named 200 icons by meaning and must rename them by depiction and retire duplicates. How do you do it without breaking consuming teams?
answer
- a name is a public contract
- old names become aliases
- deprecate in a minor, remove in a major
- duplicates redirect to a survivor
- old names live on as keywords
basics
~20 sShip the new depiction names with the old ones kept as deprecated aliases, and map each duplicate to its survivor, in a minor release. Remove old names only in a later major release, once usage shows teams have migrated.
solid answer
~50 sIcon names are a **public contract**: code and design files reference them, so renaming is a breaking change unless handled in steps. First, a **mapping table**: each meaning name to its depiction name (`buy-ticket` to `ticket`), and each duplicate to its survivor (`opening-hours` and `timed-entry` clocks to one `clock`). Then a **minor release** ships the new names with old ones kept as **deprecated aliases**, applied to the code package and the design library together, so nothing breaks and warnings point to replacements. Semantic versioning requires marking deprecation in a minor release and removal only in a major, after at least one minor carrying the deprecation. I would track old-name usage across consumers, help migration with automated renames, and remove the aliases in a **major release** once usage is near zero. Old names stay as **search keywords** so memory still finds the icon.
go deeper
Recall that an icon's name is referenced by code and design files, so renaming it without keeping the old name working breaks consumers.
Explain aliases with deprecation markers, the minor-then-major sequence semantic versioning prescribes, and why old names stay as search keywords.
Demonstrate a full plan: a reviewed mapping table, survivors chosen for duplicates, design and code renamed together, usage tracking and automated migration.
Weigh a one-time mass rename against living with a flawed scheme, counting migration cost across every consuming team against years of duplication.
## Why a rename is a breaking change An icon's name is how consumers reference it: product code imports or looks it up by name, design files link to it, documentation mentions it. Changing a name without a transition makes every reference fail at once. That is why renaming, even when only names change and not a single drawing moves, has to be treated as a change to a **public contract**. The organisation's general deprecation policy (timelines, communication channels) is set at governance level; this answer covers the icon-specific mechanics. ## Step 1: build the mapping Start with a complete table, reviewed before anything ships. For a museum ticketing kiosk's library it might include: | Old name | New name | Action | |---|---|---| | `buy-ticket` | `ticket` | Rename; old name becomes an alias | | `audio-guide` | `headphones` | Rename; old name becomes an alias | | `opening-hours` | `clock` | Rename; survivor of a duplicate pair | | `timed-entry` | `clock` | Retire the duplicate drawing; alias to the survivor | | `cloakroom-old` | none | Retire; unused according to usage data | For duplicates, pick the **survivor** by style fit and usage, not by which name sounds better, and check that the survivor's drawing works in every context the duplicate served. ## Step 2: ship in two releases Semantic versioning gives the sequence. Its rules say a MINOR version must be incremented when public API functionality is marked as deprecated, a MAJOR version is for incompatible changes, and its FAQ asks for at least one minor release containing the deprecation before removal in a major. Applied to icons: 1. **Minor release: add and deprecate.** New depiction names ship; every old name remains as an **alias** that resolves to the new icon and carries a **deprecation marker** naming its replacement. Nothing breaks. 2. **Migration window.** Consumers see warnings in their tooling and in the documentation; automated renames across repositories and design files do most of the work; usage tracking shows who still references old names. 3. **Major release: remove.** When usage of old names is near zero, or the announced window ends, the aliases are removed. The few remaining consumers get a direct heads-up first. ## Retiring icons Retirement comes in three kinds, and each needs a different path: - **Duplicates**: the name redirects to the survivor as an alias, then follows the same deprecate-then-remove sequence. - **Unused icons**: removed from search immediately so no new usage appears, but kept resolvable until the major release in case usage data missed someone. - **Icons whose metaphor changed**: a visual change for every consumer, so it is communicated as one, not slipped into a rename. ## Keep design and code in step If the code package is renamed while the design library keeps old names, designers hand off specs referencing names engineers can no longer find, and vice versa. The rename and the aliases must land in **both** in the same release, with the same mapping table as the source of truth. ## Common mistakes Most failed icon renames fail in one of a few predictable ways: - **Renaming in place** with no aliases, on the grounds that no drawing changed; every reference breaks at once. - **Adding and removing in one release**, which gives consumers no window to migrate. - **Choosing a duplicate's survivor by name** rather than by drawing, then discovering it does not work in one of the contexts the retired icon served. - **Renaming one side first**, code before the design library or the reverse, so handoffs reference names the other side cannot find. - **Forgetting search**, so people who remember the old names conclude the icons were deleted and draw new ones. ## What survives removal People remember old names for years. After the aliases are removed from code, the old names should stay as **search keywords** on the renamed icons. A keyword resolves nothing in code, so it keeps no old contract alive, but anyone searching 'buy ticket' still finds `ticket`. The rename then costs consumers one migration and nothing afterwards.
- How do you know when it is safe to remove the old names?Measure it: scan consuming repositories and design files for old names, or collect deprecation warnings, and remove in a major release once usage is near zero or the announced window has ended. Contact the remaining holdouts directly before the release rather than letting their builds discover it.
- Why keep old names as search keywords after the aliases are removed?People keep searching for names they learned. A keyword only aids search and resolves nothing in code, so it keeps no deprecated contract alive, yet anyone typing the old name still finds the renamed icon.
saying these in an interview costs you the question
- Renaming icons is safe because no drawing changes.
- Old names should be removed in the release that adds the new ones.
- Marking icon names deprecated only needs a patch release.
- The design library can be renamed later, after the code package.
- Duplicate icons can be deleted outright without redirecting their names.