Deprecation

Overview

Deprecations are an essential part of maintaining a healthy and scalable design system. Deprecation is the process of phasing out components, patterns, or tokens that are no longer aligned with current design or development standards. This typically happens when better alternatives are introduced, when existing solutions cause inconsistency or confusion, or when updates to accessibility, performance, or usability guidelines make older implementations obsolete.

“Deprecation” does not mean “immediate removal”. It means something is marked as “should not use” as early as possible. It stays available while teams migrate away from it, and is removed in a later minor release once it's no longer in use. Where possible, a deprecation includes a recommended migration path, including a codemod (if possible), which automates the migration for you. AI-Assisted Tooling, including the SWAN Deprecation skill, can also help you handle deprecations.

How deprecated items are removed

SWAN no longer uses major versions to remove deprecated items. Every migration follows the same steps:

  • Announcement: the item is deprecated in a minor release. We announce what is changing, why, what you need to do, and by when.
  • Migration window: you typically have about six months, covering two quarterly planning cycles. Complex migrations get longer. During this time we provide migration guidance, codemods where possible, and support, and send reminders.
  • Resolving outstanding work: as the deadline nears, we work directly with teams that still have usages. If work remains unresolved, we escalate it to leadership.
  • Removal: once usage on the VistaPrint website (Ubik) reaches zero, the item is removed in a minor release.

Because removals ship in minor releases, SWAN does not follow semantic versioning. The RFC: A new approach to migrations in SWAN explains why. If your application doesn't run on Ubik (for example, an internal tool), pin an exact SWAN version in your package.json. We announce changes that affect builds in advance, such as dropping CommonJS or older React versions.

Our commitments

For any migration that needs action from your team, we commit to:

  • Checking first whether the change can be made in place, so no migration is needed
  • A clear reason for the change and a migration path
  • An appropriate amount of time, typically six months, and only one large-scale migration at a time
  • Documentation, tooling, and support
  • Clear, repeated communication, and visibility into your team's outstanding work

For the full process, including timelines and escalation steps, see the SWAN Migration Process Lifecycle on Confluence.

A list of deprecations per SWAN version is listed below. Deprecations are also marked in code, in the changelog, on relevant documentation pages, and in Figma.


SWAN v3 deprecations

The preview has been updated.