skip to content

In a design system, why is a component deprecated first and removed later instead of being deleted in a single release?

level: juniorimportance: must knowfreq 38%

answer

  1. nobody breaks without warning
  2. still works, but warns
  3. time to migrate on their schedule
  4. removal is a breaking change
  5. minor to deprecate, major to remove

basics

~20 s

Deprecation keeps the component working while warning consumers and naming its replacement, giving teams a support window to migrate on their own schedule; removal comes later in a major release, so no product breaks without warning.

solid answer

~40 s

Deleting a component in one release breaks every product still using it the moment its team upgrades, with no time to plan. Deprecating first splits the change in two. The component is **marked deprecated** but keeps working, and it produces warnings and documentation notices that name the replacement and link a migration guide. Teams migrate within a published **support window**. **Removal** comes later, in a major release, because taking away public API is a backward-incompatible change. Semantic versioning backs this up: marking public API as deprecated requires a minor version increment, and its FAQ recommends at least one minor release carrying the deprecation before removal in a major. For a consumer, a deprecation notice means plan the migration now, not when removal arrives.

go deeper

for a junior

Recall the difference between deprecating and removing, and that a deprecated component still works while pointing you to its replacement and a migration guide.

for a middle

Explain why removal belongs in a major release and deprecation in a minor one under semantic versioning, and what the support window gives consuming teams.

for a senior

Show how you run the lifecycle across code and design library: warnings, docs, tracked usages and a firm removal release announced well in advance.

for a principal

Frame the deprecation lifecycle as a trust contract: predictable retirement is what keeps teams upgrading, and breaking it once costs adoption for years.

## Deprecation versus removal In a **design system**, retiring a component happens in two distinct steps: - **Deprecation** is an announcement: the component is still shipped and still works, but it is marked as on its way out, with a named replacement and a date or release after which it will be removed. - **Removal** is the actual deletion of the component from the system's packages and design library. On a travel-expense tool, for example, the old receipt uploader might be deprecated in favour of a new file-upload component that also handles multiple receipts and camera capture on mobile. For some months both exist; then the old one goes. ## What goes wrong with deleting in one release If the old uploader were simply deleted in the next release: - Every product still using it would **fail to build or render** as soon as its team upgraded. - Teams would face an **unplanned migration** in the middle of other work, often discovering it from a broken build rather than a notice. - Many teams would respond by **not upgrading** at all, which leaves them without fixes and new components and erodes the system's reach. - Some would **copy the deleted component** into their own code, creating forks that never receive fixes. The common problem is that the cost of change lands on consumers with no warning and no choice of timing. ## The two-step lifecycle 1. **Deprecate.** Mark the component as deprecated in the code package and the design library, update its documentation page with the replacement and a migration guide, and announce it in the release notes. 2. **Support window.** For a published period the component keeps working. Development-time warnings and documentation notices remind teams; the system team tracks remaining usages and helps where migration is hard. 3. **Remove.** When the window closes, delete the component in a **major release**, announced in advance, so teams that have migrated notice nothing and teams that have not can see exactly what to do. ## What semantic versioning says Many design systems version their packages with **semantic versioning** (MAJOR.MINOR.PATCH). Two of its rules shape deprecation: | Step | Semantic versioning rule | Effect | |---|---|---| | Marking a component deprecated | The minor version must be incremented when public API functionality is marked as deprecated | Consumers can adopt the release safely; nothing is removed yet | | Removing it | The major version must be incremented for any backward-incompatible change to the public API | Consumers can see from the number that the upgrade needs work | The specification's FAQ adds a recommendation: update the documentation, issue a minor release with the deprecation in place, and have **at least one minor release containing the deprecation** before the functionality is removed in a new major release, so users can transition smoothly. That is advice rather than a hard requirement, but it matches the lifecycle above. ## What a consumer should do on seeing a deprecation - **Read the notice and the migration guide**, not just the warning text. - **Plan the migration inside the support window**, ideally soon, while the system team is actively helping. - **Run any provided automated migration** and review the result, then handle the cases it flags. - **Raise blockers early**: if the replacement cannot do something the old component did, the system team needs to know before the removal date, not after. - **Do not copy the old component** into the product to keep it forever. ## Why it matters for the whole system A design system only works if consumers trust upgrades. Deprecation also has a cost for the system team: during the window it maintains two components, answers questions about both, and keeps two sets of documentation current. That cost is the price of not breaking consumers, and it is why a support window should be long enough to be fair but not open-ended. A predictable deprecation lifecycle is part of that trust: teams learn that nothing disappears without notice, a replacement and a guide, and a reasonable window. The same lifecycle applies to every platform the system ships: a native mobile package deprecates and removes components on the same pattern, and the design library marks the old component so designers stop placing it in new work.

  • Why should the design library mark a component deprecated at the same time as the code?
    Otherwise designers keep placing the old component in new designs, and engineers are handed work that uses a component they are being asked to migrate away from. Marking it in the design library, with a pointer to the replacement, stops new usages at the source while existing screens migrate.
  • Is a deprecation warning the same as a breaking change?
    No. A deprecation changes nothing about how the component works; it adds a warning and documentation. That is why semantic versioning puts it in a minor release. The breaking change is the later removal, which is why that step needs a major release and advance notice.

saying these in an interview costs you the question

  • Deprecated means the component stops working in the next release.
  • Removing a deprecated component is fine in a minor release since it was announced.
  • A deprecation notice can be ignored until the component is actually removed.
  • Deprecation only needs a changelog line; the docs and design library can stay as they are.
  • Copying the deprecated component into the app is a safe way to avoid migrating.