Migration

SWAN x elev8

SWAN is a major delivery mechanism for some of the larger goals of the elev8 initiative. As such, there are a few key milestones of SWAN to be aware of.

See more information on elev8 planning and how SWAN will roll out elev8.

v2 Minor versions

To allow teams the maximum time to update token usage, we've released our new token architecture in parallel to the existing one. Codemods exist to support this upgrade, and you may see small visual changes that require VQA, as mentioned below. However, none of these changes are breaking; running the codemods prior to v3.0 just better prepares you for the v3.0 upgrade.

v3.0 Major version

This is a large update that contains many API-breaking changes, and a few visual changes. Namely, there are many removals around legacy props, components, tokens, and otherwise. This version also removes the old token architecture, meaning if you are still using old tokens, you will be forced to upgrade now.

Visually, there are minor changes to space and color, but you should expect larger changes to typography if you were not already using the x scale, originally introduced in SWAN 1.3.

v3.3 Minor version

Acting as a counterpart to v3.0, this is the visual language update, containing many visual changes that will require VQA. Visual language updates include changes to color, typography, shape, space, and more.

Although there are many visual changes, the goal for this release has always been no required engineering effort. Designers have tested these changes early but Engineering may be needed to help fix things found in VQA.

Codemods

SWAN v3 is our first major version to be supported by the new SWAN-CLI tool! We've written a ton of codemods to make your life easier and speed up the upgrade process.

Before running codemods, please read these guidelines carefully!

Check what version of SWAN your codebase is using. Each codemod is tied to a major.minor.patch version of SWAN. This is the minimum version your codebase must be on before you can run that codemod, because it may reference new features/functionality that were introduced in that version.

Run codemods in small batches. By running a few codemods at a time, you can more easily track, test, and revert changes. For example, it is recommended to run typography, color, and other token related codemods by themselves, since they are likely to make a lot of changes that need careful review.

Run codemods tied to major versions in isolation. Codemods tied to major versions are not guaranteed to be idempotent - they may not yield the same results if run multiple times. For example, the v3.0.0 codemod "migrate spacing prop values" CAN ONLY RUN ONCE. We change the values of some of our spacing props, and every sebsequent execution will make your UI spacing will get larger and larger.

Work with your designer to VQA the changes after you run the codemods. Not every codemod is an exact 1:1 replacement. For example, the codemods to move to the new typography scale may introduce slight differences in font size. There are also significantly fewer colors available in SWAN 3.0 than before, so the codemods to migrate color tokens will convert multiple legacy tokens to the same new color token, introducing some visual differences.

If you find a issue with codemods, but you can easily upgrade manually, do so. It takes time to fix codemods, and we may not be able to even fix issues that are spotted. Anything that is being performed by a codemod should be documented on the docsite. Most likely on the main migration page listed above, but more specialised info is documented on relevant pages, such as component pages. If you can't find the information, please ask us, so we can update the documentation or point you to the right place.

Please see Codemods for more information.

Deprecations

SWAN v3 removes a lot of bloat that we've been carrying for multiple versions, including some decisions made back in Visage. As such, SWAN v3 removes many deprecated components, props, etc.

You can see the full list on our Deprecation Roadmap.

Find more information on tokens below.

Tokens

SWAN v3 includes a major overhaul of our design token architecture.

Importing

We’ve drastically reduced the inconsistency across supported languages. Many JS-only objects are removed, and SCSS no longer has special ‘non-literal value’ tokens.

The import path for SCSS/LESS/CSS/Stylus is simply:

@use '~@vp/swan/tokens';

Javascript is slightly different, and as imported from the main path:

import { tokens, tokensRaw } from '@vp/swan'

Figma

We also moved our SWAN UI Kit from styles to variables, which offer better support for modes, breakpoints, etc. For more information, see Designers.

Tiers

New tokens have three tiers noted in the token itself, each tier refers to the tier above it:

1. Base - base tokens are an abstraction over raw values. They represent the scale and options for other tokens to pull from.
2. Semantic - semantic tokens represent shared design decisions.
3. Component - component tokens represent outlier decisions for necessary components. Not for public consumption.

The goal is to use the most semantic token possible. Thus, users should always aim to use a semantic token, using only a base token when necessary.

For more information, see Tokens.

Modes

For more consistency with how our modes are named, lightMode has been replaced with standardMode. compactMode is a new mode to support denser UI for workspace-like views. For more information, see Modes.

Component tokens

We took a conscious approach to moving away from component tokens in SWAN 3.0. Before, they were often used as an escape hatch for inconsistency, and were used for snowflakes or custom components in an undesirable way. We’ve made SWAN a bit more internally consistent, and semantic tokens should take their place.

Props

Various React props reference our tokens through an abstraction. In v3.0 these have also changed to allow for more semantics, and to reflect the removal of their underlying tokens.

If you are upgrading SWAN prior to v3.0, note the warnings above tables to ensure you're migrating props at the correct time. In an effort to not create inconsistency, some props point to old tokens until v3.0 where they will be consolidated.

Migration tables can be found at the bottom of this document. For the rainbow palette and other marketing colors, see: Removing our old brand and marketing colors.

Objects

We’re removing the JS-only objects as these tokens often were out-of-date and represented unwanted solutions. Instead, users should use the equivalent JS token, which holds the same information and more appropriately reacts to modes.

The exception to these removals is MARKETING_COLORS which has been move to @vp/marketing-colors library.

Migrating old tokens

The All Tokens page has a list of all new tokens.

We also have a spreadsheet of the list of replacements for existing tokens. The tokens listed in the spreadsheet are language-agnostic, and must be prefixed with 'swan' appropriately. For example, base.color.transparent is equivalent to $swan-base-color-transparent in SASS, and SwanBaseColorTransparent in JS. The 'difference' column notes the breadth of the change, with some tokens intentionally not having a replacement (usually marked as 'breaking').

Codemods exist to automate both the token changes and prop changes mentioned above. Many have already been released, with a few more set to be released with SWAN 3.0. These codemods will handle the bulk of the migration, but as always, we advise caution and QA, and note that the codemods can't cover everything.

Unfortunately, we can’t automate a migration to some semantic tokens, since they require knowledge of the intent of each use case. We encourage you to inspect you token usage and ensure you are using the most semantic token applicable. The more semantic usage, the stronger and more accurately new visual updates will propagate through Vista.

Note that, when possible, tokens now point to CSS Custom Properties. This means that you can no longer rely on literal values and perform interpolation or similar on tokens.

FAQs

Token-related prop replacements

backgroundColor

For the rainbow palette and other marketing colors, see: Removing our old brand and marketing colors, and review the table below.

textColor

fontSize

fontFamily

fontWeight

fontSkin

fontSkin contains 5 styling decisions (fontSize, fontFamily, fontWeight, lineHeight, letterSpacing). It's an extra migration to get ensure you're using the most semantic token. When moving to fontSkin, you should remove all other styling.

fontFamily is replaced by Output font in the below table, due to the props changing between v2.22 and v3.0.

Ensure the resulting fontSkin used matches the semantics and design intent of the page.

space (margin, padding, etc)

Miscellaneous

Typescript Types

• The StyleSpacing0to13 type should be replaced with StyleSpaceWithAuto
• The ScreenClasses type should be replaced with StyleBreakpoints

SCREEN_CLASS_MIN_WIDTHS, SCREEN_CLASS_MAX_WIDTHS

The deprecated Screen Class objects should be replaced with tokens.

import { tokensRaw } from '@vp/swan'