How to Migrate Your Project to New Design Tokens

Follow these steps to migrate your codebase from old design tokens to the new token system:

1. Prepare your codebase

   Before running the migration, make sure to commit or back up your code. This ensures you can revert changes if needed.

2. Install the codemod CLI tool

   Run the following command in your terminal to install the codemod CLI:

   npm install -g codemod

3. Run the migration codemod

   Navigate to your project directory and run:

   npx codemod@latest path-to-migration-codemod --engine=workflow

   Replace “path-to-migration-codemod” with the path you received from your design system team.

4. Review the changes

   The codemod will list all files that were modified. Review these changes carefully to ensure they look correct.

   Pay special attention to:

   • Imports/variables that reference design tokens
   • CSS/SCSS/LESS variables using token values
   • JavaScript/TypeScript token references
5. Test your application

   Run your application and verify that all styles and components render correctly with the new tokens.

   Some components might need manual adjustment if they relied on specific values from the old token system.

6. Fix any remaining issues

   If you encounter any visual bugs or errors, you may need to:

   • Check if any tokens were missed in the migration
   • Look for dynamic token usage that the codemod couldn't detect
   • Update components that depend on specific token values

This migration uses ast-grep for precise, reliable token replacements. If you find any tokens that weren't properly replaced, contact your design system team for assistance.