deprecation-process

Deprecation process

A skill for planning and executing the deprecation of components, tokens, or patterns in a design system. Produces a deprecation plan with timeline, consumer communication, and migration guidance.

Context

Deprecation is the maintenance work that never gets prioritised until it becomes a crisis. Components accumulate. Tokens multiply. Patterns fork. The longer a team waits to deprecate, the more existing usage entrenches, and the more a removal feels disruptive rather than healthy.

A deprecation done well is a contract with consumers: clear notice, a migration path, and a credible timeline. A deprecation done badly is a surprise, and it erodes trust in the system faster than almost anything else.

This skill produces a deprecation plan that is honest about the timeline, specific about migration, and structured to communicate clearly to the teams affected.

---

Step 1: Identify what is being deprecated

Clarify:

• What is being deprecated? (component, token, pattern, variant, API)
• Why is it being deprecated? (superseded by a better option, unused, causing maintenance burden, design direction change, accessibility non-compliance, etc.)
• What replaces it, if anything?
• Is there a hard removal date in mind, or is this open-ended?

If nothing replaces it: the deprecation plan needs an extra step addressing why the use case should no longer be served and what teams who relied on it should do instead.

Step 2: Audit current usage

Before writing the plan, understand the exposure. Do not estimate when you can measure.

Automated usage counting (if codebase access is available):

Run these searches to produce a concrete usage count, not an estimate:

For component deprecation:

# Count import statements
grep -r "import.*{.*ComponentName" --include="*.tsx" --include="*.ts" --include="*.jsx" --include="*.js" src/ | wc -l

# Count JSX usage (may exceed imports if used multiple times per file)
grep -r "<ComponentName" --include="*.tsx" --include="*.jsx" src/ | wc -l

# List files with usage (for blast radius mapping)
grep -rl "import.*ComponentName\|<ComponentName" --include="*.tsx" --include="*.ts" --include="*.jsx" --include="*.js" src/