@workday/canvas-kit-docs/dist/mdx/tokens/TokenMigrationCodemod.mdx

Documentation components of Canvas Kit components

# Canvas Kit Tokens Migration Codemod

This codemod helps migrate Canvas Kit tokens from `@workday/canvas-kit-react/tokens` or
`@workday/canvas-tokens-web` v2 to `@workday/canvas-tokens-web` v3 format. It automatically
transforms token usage in your codebase to use the new token system.

## Important Notes

- **Run on Small Batches**: We recommend running the codemod on a small number of files in batches
  instead of your entire repository all at once. This makes the changes easier to review and allows
  you to catch issues more quickly with less frustration. This allows for easier manual review of
  the changes and helps catch any potential issues early.
- **Use System Tokens**: You should generally always opt to use system (semantic) tokens over base
  tokens. This clarifies the token's intent, simplifies future updates to new tokens, and maintains
  better consistency across your codebase.
- **Codemod Limitations**: The codemod does not cover every possible token usage or migration
  scenario. Please review the codemod's changes and be prepared to update tokens as needed. Some
  manual changes will be required, especially for:
  - Custom or dynamic token usages
  - Inline styles, string templates, or non-standard patterns
  - Updating documentation, comments, or non-code files
  - Ensuring correct semantic token choices for your specific use case

## Required Dependencies

The codemod requires the following packages to be installed:

- `@workday/canvas-kit-styling`
- `@workday/canvas-tokens-web`. See
  [instructions here](/docs/guides-tokens-migration-installation-setup--docs).

## Installation

You can run the codemod using npx:

```sh
npx @workday/canvas-kit-codemod v14-tokens [path]
```

Or install the package and run it directly. But remember to uninstall the package after you have
completed the upgrade.

```sh
yarn add @workday/canvas-kit-codemod
canvas-kit-codemod v14-tokens [path]
```

> Note: These codemods only work on .js, .jsx, .ts, and .tsx extensions. You may need to make some
> manual changes in other file types (.json, .mdx, .md, etc.).

> Note: You may need to run your linter after executing the codemod, as its resulting formatting
> (spacing, quotes, etc.) may not match your project's styling.

## What This Codemod Does

The codemod transforms the following tokens:

- [Colors](#colors)
- [Depth](#depth)
- [Shape](#shape)
- [Space](#space)
- [Typography](#typography)

### Colors

- Converts color tokens from `@workday/canvas-kit-react/tokens` to the new system
- Transforms color usage in `createStyles`, `createStencil`, and CSS objects
- Maps old color tokens to new semantic color tokens
- Adds required imports for `cssVar` and new token packages

#### Color Token Mappings to System

##### Background Colors

| Old Token                 | New Token                           |
| ------------------------- | ----------------------------------- |
| `colors.frenchVanilla100` | `system.color.bg.default`           |
| `colors.blueberry200`     | `system.color.bg.primary.soft`      |
| `colors.blueberry400`     | `system.color.bg.primary.default`   |
| `colors.blueberry500`     | `system.color.bg.primary.strong`    |
| `colors.blueberry600`     | `system.color.bg.primary.stronger`  |
| `colors.cantaloupe100`    | `system.color.bg.caution.softer`    |
| `colors.cantaloupe400`    | `system.color.bg.caution.default`   |
| `colors.cantaloupe500`    | `system.color.bg.caution.strong`    |
| `colors.cantaloupe600`    | `system.color.bg.caution.stronger`  |
| `colors.cinnamon100`      | `system.color.bg.critical.softer`   |
| `colors.cinnamon500`      | `system.color.bg.critical.default`  |
| `colors.cinnamon600`      | `system.color.bg.critical.strong`   |
| `colors.greenApple100`    | `system.color.bg.positive.softer`   |
| `colors.greenApple400`    | `system.color.bg.positive.default`  |
| `colors.greenApple500`    | `system.color.bg.positive.strong`   |
| `colors.greenApple600`    | `system.color.bg.positive.stronger` |
| `colors.licorice100`      | `system.color.bg.muted.softer`      |
| `colors.licorice200`      | `system.color.bg.muted.soft`        |
| `colors.licorice300`      | `system.color.bg.muted.default`     |
| `colors.licorice500`      | `system.color.bg.muted.strong`      |
| `colors.soap100`          | `system.color.bg.alt.softer`        |
| `colors.soap200`          | `system.color.bg.alt.soft`          |
| `colors.soap300`          | `system.color.bg.alt.default`       |
| `colors.soap400`          | `system.color.bg.alt.strong`        |
| `colors.soap500`          | `system.color.bg.alt.stronger`      |
| `colors.blackPepper400`   | `system.color.bg.contrast.default`  |
| `colors.blackPepper500`   | `system.color.bg.contrast.strong`   |

##### Foreground Colors

| Old Token                 | New Token                          |
| ------------------------- | ---------------------------------- |
| `colors.blackPepper300`   | `system.color.fg.default`          |
| `colors.blackPepper400`   | `system.color.fg.strong`           |
| `colors.blackPepper500`   | `system.color.fg.stronger`         |
| `colors.blueberry400`     | `system.color.fg.primary.default`  |
| `colors.blueberry500`     | `system.color.fg.primary.strong`   |
| `colors.cinnamon500`      | `system.color.fg.critical.default` |
| `colors.frenchVanilla100` | `system.color.fg.inverse`          |
| `colors.licorice100`      | `system.color.fg.disabled`         |
| `colors.licorice200`      | `system.color.fg.muted.soft`       |
| `colors.licorice300`      | `system.color.fg.muted.default`    |
| `colors.licorice400`      | `system.color.fg.muted.strong`     |
| `colors.licorice500`      | `system.color.fg.muted.stronger`   |

##### Border Colors

| Old Token                 | New Token                              |
| ------------------------- | -------------------------------------- |
| `colors.blackPepper400`   | `system.color.border.contrast.default` |
| `colors.blackPepper500`   | `system.color.border.contrast.strong`  |
| `colors.blueberry400`     | `system.color.border.primary.default`  |
| `colors.cantaloupe400`    | `system.color.border.caution.default`  |
| `colors.cantaloupe600`    | `system.color.border.caution.strong`   |
| `colors.cinnamon500`      | `system.color.border.critical.default` |
| `colors.frenchVanilla100` | `system.color.border.inverse`          |
| `colors.licorice100`      | `system.color.border.input.disabled`   |
| `colors.licorice200`      | `system.color.border.input.default`    |
| `colors.licorice500`      | `system.color.border.input.strong`     |
| `colors.soap300`          | `system.color.border.input.inverse`    |
| `colors.soap400`          | `system.color.border.divider`          |
| `colors.soap500`          | `system.color.border.container`        |

##### Other Colors

| Old Token                      | New Token                           |
| ------------------------------ | ----------------------------------- |
| `colors.blackPepper600`        | `system.color.static.black`         |
| `colors.toastedMarshmallow600` | `system.color.static.gold.stronger` |

### Depth

- Converts depth tokens to objects with `boxShadow` property
- Handles special case for depth[0] (converts to `boxShadow: "none"`)
- Transforms depth tokens in nested CSS selectors
- Handles depth tokens in component props

### Shape

- Converts border radius tokens to
  [new shape tokens](/docs/guides-tokens-migration-mapping-tables-system--docs#shape-border-radius-token-migration)
- Transforms `borderRadius.m` to `system.shape.x1`

### Space

- Converts all space tokens to the new system tokens
- Maps old space values to
  [a new scale](/docs/guides-tokens-migration-mapping-tables-system--docs#space)

### Typography

- Converts font family tokens to
  [new system tokens](docs/guides-tokens-migration-mapping-tables-system--docs#font-family)
- Transforms font size tokens to
  [new system tokens](docs/guides-tokens-migration-mapping-tables-system--docs#font-size)
- Converts font weight tokens to
  [new system tokens](docs/guides-tokens-migration-mapping-tables-system--docs#font-weight)
- Handles type levels and their properties
- Transforms typography in component styles

## What to Expect

After running the codemod, your code will:

1. Use the new token system with `cssVar` and system tokens
2. Have updated imports for the new token packages
3. Use semantic color tokens instead of direct color values
4. Have consistent spacing and typography using the new scale

## Example Transformations

### Before

```typescript
import {colors} from '@workday/canvas-kit-react/tokens';

const styles = createStyles({
  background: colors.frenchVanilla100,
  color: colors.blueberry400,
});
```

### After

```typescript
import {cssVar} from '@workday/canvas-kit-styling';
import {base, system} from '@workday/canvas-tokens-web';

const styles = createStyles({
  background: system.color.bg.default,
  color: system.color.fg.primary.default,
});
```

## Summary

- The codemod handles various edge cases including aliased imports and nested CSS selectors
- It preserves existing code structure while updating token usage
- It adds necessary imports automatically
- It handles template literals and spread operators in CSS objects
- It maintains proper type safety through the transformation process