What should a design system's deprecation policy define so that retiring a component never strands a consuming team?
answer
- rules written before the first case
- why and when to deprecate
- a minimum window with an end date
- replacement plus migration guide
- track usages, remove only at a major
basics
~20 sCriteria for deprecating, how it is announced and marked in code and design library, a minimum support window with a known end, a replacement and migration guide first, usage tracking, and removal only in a major release.
solid answer
~40 sA deprecation policy turns each retirement from a negotiation into a known process. It should state **when** a component may be deprecated, for example when a replacement exists and is stable; **how** it is announced and marked, in release notes, docs, development-time warnings and the design library; a **minimum support window** with a published end, scaled to how widely the component is used; that a **replacement and migration guide** exist before deprecation starts, plus an automated migration where the change is mechanical; how **remaining usages are tracked** and reported; and that **removal happens only in a major release**, announced in advance. It should also say how extensions are granted, so the rare exception is handled by rule rather than by whoever complains loudest.
go deeper
Recall that a deprecation policy sets how teams are told, how long they have, and what help exists, such as a replacement and a migration guide.
Explain each element of the policy and why the replacement and guide must exist before the support window starts.
Show how you scale the support period to impact, run the communication touchpoints across code and design library, and grant extensions by rule rather than by pressure.
Discuss how strict or generous a policy should be for your organisation, and why a policy that is always honoured beats a generous one that is not.
## Why write a policy at all Without a written **deprecation policy**, every retirement in a **design system** is negotiated from scratch: how long teams get, whether there is a guide, what happens to stragglers. Consuming teams cannot plan, and the loudest team usually sets the terms. A policy written before the first deprecation makes retirement predictable, which is what keeps teams willing to upgrade. The aim is simple: no team should ever discover that a component is gone before it had a fair chance to move. ## What the policy defines | Element | What it says | Example on a travel-expense tool | |---|---|---| | Criteria | When a component may be deprecated | The old button may be deprecated once the new button covers every documented use | | Preconditions | What must exist first | A stable replacement, a migration guide, and a codemod if the change is mechanical | | Announcement | Where and how teams hear about it | Release notes, a docs banner, development-time warnings, design library marking | | Support window | Minimum time before removal | At least two release cycles; longer for components used in most screens | | Usage tracking | How remaining usages are counted and shown | A per-team count of old button usages, published with each release | | Removal | When and how it happens | Only in a major release, announced at least one cycle ahead | | Extensions | How exceptions are granted | Only for blockers the replacement causes, time-boxed and recorded | ## The support window The **support window** is the time during which a deprecated component keeps working and is supported. The policy should make it: - **Measured from the announcement**, not from when the replacement was merged, so teams get the full period. - **Scaled to impact.** A rarely used component can go quickly; a component used on most screens, like a button, needs longer. - **Fixed in advance**, with a known end release or date, so teams can schedule the work. - **Clear about what support means**, for example whether defects in the old component are still fixed, or only severe and accessibility defects. The exact length is a choice each organisation makes; what matters is that it is published and honoured. ## The migration guide A deprecation without a guide leaves every team to rediscover the same answers. A good **migration guide**: 1. Names the replacement and says why the change is worth making. 2. Maps each old option to its new equivalent, including ones with no direct equivalent. 3. Shows before-and-after examples for the common cases. 4. Lists behaviour differences, such as a changed focus style or different default size, that teams should check on screen. 5. Explains how to run the automated migration, if there is one, and which cases it leaves for manual work. 6. Says where to ask for help. The guide should cover every platform the system ships, and the design library side too: how designers swap the old component for the new one in existing files. ## Communication touchpoints Teams notice a deprecation in different places, so the policy names all of them: - **Release notes** of the release that deprecates the component. - **The component's documentation page**, with a banner, the replacement and the removal release. - **Development-time warnings** when the old component is used, in wording that names the replacement. - **The design library**, where the old component is marked and kept out of the default set designers insert from. - **Reminders** as the removal release approaches, targeted at teams that still have usages. ## Exceptions and removal The policy should expect exceptions and constrain them: extensions are granted when the **replacement** blocks a team (a missing capability the system must fix), not when a team simply has not prioritised the work, and every extension is time-boxed and recorded. Removal then happens in a **major release**, because it is a backward-incompatible change, and is announced at least one cycle ahead. A policy that is honoured every time is worth more than a generous one that is broken whenever it is inconvenient.
- Why should a replacement and migration guide exist before a component is deprecated, not after?Because deprecation starts the clock on the support window. If teams are told to migrate before there is something to migrate to, the window is spent waiting, and early movers may migrate to an unfinished replacement. Requiring both first means every day of the window is usable migration time.
- What should decide whether a team gets an extension past the removal date?Whether the blocker is the system's or the team's. If the replacement lacks something the old component did, the system owes a fix or an extension. If the team simply did not schedule the work, the published date should hold, since the old major remains available to them for a while.
saying these in an interview costs you the question
- Each deprecation can be negotiated case by case; a written policy adds bureaucracy.
- The support window can start before a replacement exists.
- A changelog entry alone is enough to announce a deprecation.
- Every team that asks should get an extension, whatever the reason.
- Migration guides only need to cover code; designers will work it out.