Migration

Codemods

Overview

What is a codemod?

A codemod is a powerful script that replaces the need for manually performing code changes. To make both major and minor upgrades easier, we offer codemods to automate as many of the manual code changes as possible.

When do I run codemods?

Technically, you are only required to make code changes when migrating to a major release, because a minor release will never introduce a breaking change that involves code changes.

However, we encourage you to run codemods during minor migrations, too! This is because we often deprecate features in minor releases to prepare for their removal in the next major release. By addressing these deprecations in your minor migrations, you’re setting yourself up for a much easier major migration later!

Which codemods do I run?

The codemods released with major versions are breaking - they can safely run only once. Run them ONLY when migrating from the previous major version.

The codemods released with minor versions are idempotent - they can be safely run more than once. Run them when your codebase is greater than or equal to its version, and less than the next major.

How to run codemods

Installation

To run the codemods, you will use the SWAN CLI, a unified tool for managing your SWAN package directly from your codebase using the command line.

The SWAN CLI is an NPX tool, so there is no need to install the package or its dependencies. However, it is required that you run the CLI using Node 18+.

npmyarn

CopyShare

npm install @vp/swan@latest npx @vp/swan-cli@latest

npm install @vp/swan@latest
npx @vp/swan-cli@latest

CopyShare

yarn add @vp/swan@latest yarn add @vp/swan-cli@latest // Add a script in your package.json { "scripts": { "@vp/swan-cli" : "@vp/swan-cli" } } // Run yarn run codemod yarn run @vp/swan-cli [commands] [options] // After the codemods are done executing, remove the script added and the package from package.json yarn remove @vp/swan-cli

yarn add @vp/swan@latest
yarn add @vp/swan-cli@latest

// Add a script in your package.json 
{
  "scripts": {
    "@vp/swan-cli" : "@vp/swan-cli"
  }
}

// Run yarn run codemod
yarn run @vp/swan-cli [commands] [options]

// After the codemods are done executing, remove the script added and the package from package.json
yarn remove @vp/swan-cli

Usage

You can simply run npx @vp/swan-cli@latest [command] [options] from the root of your codebase to invoke the latest and greatest version of the tool. Replace [command] and [options] with any of the flags below to customize your experience.

Commands

--run

Runs the codemod CLI, allowing you to select the directory to execute against, and which codemods to execute.

npx @vp/swan-cli@latest run

Options (optional):

--from

The minimum version, inclusive, to include in the preselection of codemods to execute. Codemods matching the from version will be run.

npx @vp/swan-cli@latest run --from=1.0.0

--to

The maximum version, exclusive, to include in the preselection of codemods to execute. Codemods matching the to version will not be run.

npx @vp/swan-cli@latest run --to=3.0.0

npx @vp/swan-cli@latest run --from=2.0.0 --to=3.0.0

--list

Lists the codemods without executing them.

npx @vp/swan-cli@latest run --list

Respects the `--from` and `--to` flag for displaying matching codemods.

npx @vp/swan-cli@latest run --list --from=2.0.0 --to=3.0.0

--verbose

When used with the `run` command, logs information about each file the transformations were run against.

npx @vp/swan-cli@latest run --verbose

When used with the `--list` option, logs all the transformations to be executed by the codemod.

npx @vp/swan-cli@latest run --list --verbose

--help, -h

When used with a command, displays help for that command.

npx @vp/swan-cli@latest run --help

When used on its own, lists available commands.

npx @vp/swan-cli@latest --help

Next steps

Once the codemods are done executing, you will see the results printed to your terminal along with some disclaimers and next steps.

Close

An example of the CLI terminal output including results, disclaimers, and next steps.

Review the disclaimers

The codemods may not fix everything that is currently deprecated. For changes that cannot be automated with a codemod, you will find migration instructions in the next major release migration guide. For changes that can be partially automated with a codemod, you will find additional effort or review instructions listed in the "Disclaimers" section of the output. Note that disclaimers are logged for all codemods that were executed, even if they didn't transform any of your files.

Run your formatter

Be sure to run your own formatter (i.e. prettier, eslint). The codemod library we use will apply its own formatting against your transformed files, and they will be ugly 🙂

Verify the changes

Verify that the changes made by the codemods are accurate, extensive, and produced zero regressions by running your test suite, booting up your application, performing visual QA, and spot-checking the diff. Keep in mind that the codemod library cannot anticipate every use case, so look closely for things it may have missed!

List of codemods

Here is an up-to-date list of all available codemods and their disclaimers, grouped by their minimum compatible SWAN version.

3.0.0

• Migrate margin*/m*, padding*/p* prop values (1 -> 2, 2 -> 3, 3 -> 4, 4 -> 5, 5 -> 6, 6 -> 7, 13 -> 12)
  • ⚠️ This codemod can only be run ONCE to migrate space props from SWAN v2 to v3.
• Migrate fontFamily prop values (graphik -> primary, secondary -> primary, special -> secondary)
• Migrate import paths for mixins to @vp/swan/mixins/*
• Remove skin prop from ThumbnailsHero component
• Rename prop names for Typography component (align -> textAlign, weight -> fontWeight)
• Rename constants and import paths for tokens (dtcgTokens -> tokens)
• Remove style keys (controlIcon, detailsBanner, embeddedTextHero, promoBar, secondaryTile, standardBanner, standardHero, combobox, menu, legacy*)
• Remove skin prop from Table component
• Rename type StyleSpacing0to13 to StyleSpaceWithAuto

2.22.0

• Rename fontWeight prop value from bolder to boldMigrate fontSize prop values (-1-6, m*, x*, xm* -> xsmall-x4large)Migrate color design tokens to the SWAN v3 token architecture
  • ⚠️ This codemod does not work on bracket object notation or with destructured values
  • ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
  • ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
• Migrate font design tokens to the SWAN v3 token architecture
  • ⚠️ This codemod does not work on bracket object notation or with destructured values
  • ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
  • ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
• Migrate component design tokens to the SWAN v3 token architecture
  • ⚠️ This codemod does not work on bracket object notation or with destructured values
  • ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
  • ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
• Migrate element design tokens to the SWAN v3 token architecture
  • ⚠️ This codemod does not work on bracket object notation or with destructured values
  • ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
  • ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
• Migrate size design tokens to the SWAN v3 token architecture
  • ⚠️ This codemod does not work on bracket object notation or with destructured values
  • ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
  • ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
• Migrate state design tokens (selected/disabled) to the SWAN v3 token architecture
  • ⚠️ This codemod does not work on bracket object notation or with destructured values
  • ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
  • ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
• Migrate base design tokens to the SWAN v3 token architecture
  • ⚠️ This codemod does not work on bracket object notation or with destructured values
  • ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
  • ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
• Migrate shadow design tokens to the SWAN v3 token architecture
  • ⚠️ This codemod does not work on bracket object notation or with destructured values
  • ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
  • ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
• Migrate spacing design tokens to the SWAN v3 token architecture
  • ⚠️ This codemod does not work on bracket object notation or with destructured values
  • ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
  • ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
• Migrate media query (mq) design tokens to the SWAN v3 token architecture
  • ⚠️ This codemod does not work on bracket object notation or with destructured values
  • ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
  • ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
• Rename textColor prop values (alert -> error, black, black-800 -> standard, dark-grey, dark-gray, grey-700, gray-700 -> subtle)
• Remove starsToShow prop from RatingsStars component

2.21.0

• Rename lightMode prop value and CSS class to standardMode
• Rename backgroundColor="loading-shimmer" prop to loadingShimmer
• Migrate backgroundColor/bgc prop values (discount -> promo, grey/gray-*, platinum, light-grey/gray -> strong, black-900 -> black, white-900/white -> standard, dark-blue, atlantic, kingfisher -> accent)

2.20.0

• Migrate constant GLOBAL_FONT to new color token
• Migrate SEMANTIC_COLORS properties to new color tokens
  • ⚠️ If you have used SEMANTIC_COLORS.selected, you may need to change SwanSemColorBgSelected to SwanSemColorBorderSelected.
• Migrate SOURCE_COLORS properties to new color tokens

2.17.0

• Remove contentWidth prop from ThumbnailsHero component
• Remove imageShadow prop from StandardTile component
• Remove skin="brand-blue" prop from Icon component
• Remove size prop from FormError, FormHelper, FormLabel components
• Rename skin prop value from accent to primary for Button component
• Rename component from ButtonSuperBreak to br
• Replace component Icon* with <Icon iconType="*">
• Remove skin="peek" prop from Accordion component
• Replace component StandardSection with Box
• Rename skin prop value from comparison to dividers for Table component
• Rename skin prop value from simple to dividers for Table component

2.13.0

• Remove borderless prop from Dropdown component
• Remove fixedWidthHeaders, size props from Tabs component
• Remove fullWidthHeader prop from Tabs component
• Remove skin="link" prop from Listbox, BasicListbox componentsRemove rich, richLastAlign props from CollapsibleSummary component
• Remove size="large" prop from Accordion component
• Remove size="mega" prop from TextInput component
• Remove size="super" prop from Callout component
• Rename 'progressIndicator prop value from fraction to none for Carousel component
• Rename prop values and components for Icon component (shoppingBag_x -> shoppingBag_0, IconShoppingBag_x -> IconShoppingBag_0, redLegacy -> redo, IconRedoLegacy -> IconRedo, undoLegacy -> undo, IconUndoLegacy -> Undo)
• Rename srOnly prop to visuallyHiddenRename skin prop value from gallery to product for StandardTile component
• Migrate textSize prop to fontSize (1 -> x4, 2 -> x3, 3 -> x2, 4 -> x1, 5 -> x, 6 -> xm1, 7 -> xm2)
• Rename skin prop value from standard to under for ThumbnailsHero component

2.5.0

• Remove rounded prop from Dropdown component
• Rename textColor prop values (alert -> error, black -> black-800, dark-grey/gray -> grey-700)
• Rename textColor prop value from black-900 to black-800

2.0.0

• Rename color constants (colors -> SEMANTIC_COLORS, sourceColors -> SOURCE_COLORS)
• Rename constant from globalFont to GLOBAL_FONT
• Rename component from LegacyModalDialog to ModalDialog
  • ⚠️ Visual QA recommended, especially if you had any snowflakes on your LegacyModalDialog.
  • ⚠️ If you have added a backgroundColor or bgc prop onto LegacyModalDialogContent, you will need to manually move that prop to ModalDialog now.
• Rename component from LegacyPopover to Popover
  • ⚠️ Visual QA recommended, especially if you had any snowflakes on your LegacyPopover.
• Rename marketing constants (marketingBackgroundTokenMapping -> MARKETING_BACKGROUNDS, marketingBackgroundColors -> MARKETING_COLORS)
• Rename component from Paginator to Pagination
• Rename component from PipeDivider to PipeSeparator
• Rename screen class constants (screenClasses -> SCREEN_CLASSES, screenClassMax/MinWidths -> SCREEN_CLASS_MAX/MIN_WIDTHS)
• Rename component from SecondaryTileBadges to SecondaryTileCallouts
• Rename spacing constants (spacing -> SPACING, spacingPx -> SPACING_PX)
• Rename component from TableTextSecondLine to TableTextNewLineRename textAlign prop to textHorizontalAlign
• Rename component from TextButton to Button
• Rename widthVariant prop to widthRemove skin prop from Collapsible component
• Rename allCaps prop to textAllCaps
• Replace component BasicPreloader with Spinner
  • ⚠️ Add the new "spinner" style key
  • ⚠️ Add the required ARIA attributes for a11y support, you can find guidelines in the docs: https://vista.design/swan/components/spinner/?tab=Usage#Accessibility
  • ⚠️ If you are using Preloader (instead of BasicPreloader), replace it manually
• Rename cardDividers prop to dividers for GridContainer component
• Rename sizeVariant prop to size
• Rename visuallyHiddenText prop to accessibleText
• Replace component ControlIcon with Icon
• Replace minimal prop with skin="minimal" in List, Ul components
  

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'