In the lifecycle of an enterprise design system, creating new components is universally celebrated. Design tokens are defined, polished Figma variants are published, and celebratory release notes are broadcast in company Slack channels. However, the true test of a design system’s governance maturity is not how it births new components; it is how it gracefully sunsets and deprecates obsolete UI elements without breaking production code or disrupting designer workflows.

As enterprise design systems scale across hundreds of product repositories, legacy components (such as an outdated button with rigid icon props, an un-semantic modal dialogue, or a legacy multi-select table) accumulate enormous design debt. When design system teams abruptly delete or make breaking changes to published Figma libraries, downstream product designers wake up to detached instances, broken component overrides, and misalignment with production React/Vue code. This forensic operational guide outlines the complete zero-downtime component deprecation playbook: semantic versioning protocols, visual deprecation warning badges in Figma, telemetry tracking, and automated codemod migrations.

How Do You Deprecate Design System Components Without Breaking Production?

The cardinal error design system teams commit is treating a shared UI library like a personal sketchbook. In an enterprise organization where 40 engineering teams build against design system packages, publishing an unexpected breaking change or deleting a component variant is the equivalent of dropping an unannounced breaking API change. It shatters the trust between design systems and product engineering teams, triggering rogue component forks and library detachment.

The 4-Stage Component Deprecation Lifecycle

The table below provides a forensic operational matrix governing each phase of the component sunsetting protocol across design, documentation, and production code:

Figma Library Tactics: Soft Hiding and Instance Preservation

When deprecating a component in Figma, design system managers often make the mistake of immediately deleting the main component. Doing so causes downstream designer files to flag ‘Component deleted from library,’ forcing designers to either manually rebuild their screens or detach the instances into raw vectors.

Instead, follow these three non-destructive Figma tactics:

1. Prefix Component Names to Soft-Hide: In Figma, adding a period (`.`) or an underscore (`_`) before a component or frame name (e.g., `._deprecated_Card`) hides it from the Assets panel and search bar for all consumer files, while allowing existing inserted instances to continue receiving style updates without breaking.
2. The Canvas Warning Banner: Add a high-visibility, striped caution banner directly inside the deprecated component frame: ‘⚠️ DEPRECATED COMPONENT — Replace with CardV2 from Core Library’. When designers review their screens, the banner immediately informs them of the required update.
3. Library Swap Component Matching: When publishing the replacement component, ensure that layer naming, auto-layout hierarchies, and nested icon properties match the legacy version as closely as possible. This allows designers to use Figma’s native ‘Swap Component’ feature with 100% text and override retention.

Engineering Automation: Codemods and ESLint Guards

Relying solely on developers to manually search and replace deprecated components across 50 enterprise repositories is a recipe for failure. Modern design systems accelerate deprecation via automated AST (Abstract Syntax Tree) transformation scripts:

• Automated Codemods (jscodeshift): When replacing `` with ``, ship an official codemod script that developers run via terminal (`npx @your-system/codemods migrate-button`). The script automatically parses the codebase, renames the JSX tags, updates import statements, and maps legacy props (e.g., `type=”primary”` to `variant=”solid”`).
• Custom ESLint Rules: Implement an ESLint rule that flags deprecated component imports during code editing. The linter warning should include an actionable hyperlink to the internal design system migration guide.

Telemetry and Usage Auditing: Building the Sunset Dashboard

You cannot responsibly deprecate what you cannot measure. Design systems teams operating without telemetry inevitably fall into the trap of subjective prioritization—preserving bloated legacy components because an outspoken engineering squad claims they ‘might still need it.’ To establish an empirical deprecation cadence, engineering leadership must instrument static code analysis scripts that crawl all enterprise GitHub/GitLab repositories on a weekly schedule.

By piping AST search metrics into a central design operations dashboard (visualized via Datadog, Metabase, or custom Grafana panels), the team gains real-time visibility into the exact number of legacy instances surviving in production. A component should only transition from Phase 2 (Soft Deprecation) to Phase 3 (Hard Deprecation) when total codebase instances drop below a pre-agreed threshold (e.g., fewer than 10 surviving call sites across all production repos). This data-driven gate eliminates political friction between product design and engineering teams, transforming deprecation from a contentious dispute into an objective, milestone-driven milestone.

For more frameworks on eliminating technical debt and managing design operations at scale, read our analysis on The Total Cost of Design Debt: Enterprise Valuation and explore ROI governance in our Design System ROI Guide.