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

Documentation components of Canvas Kit components

import {AIIndicator, DownloadLLMFile} from '@workday/canvas-kit-docs';
import {StorybookInformationHighlight} from './StorybookInformationHighlight';


# Canvas Kit Token Migration Guide: Moving to `@workday/canvas-tokens-web`

Canvas Kit v10+ introduces a new token system that replaces the old JavaScript-based tokens from
`@workday/canvas-kit-react/tokens` with CSS variables from `@workday/canvas-tokens-web`.

## Why Migrate?

- **Better Performance**: CSS variables eliminate the runtime cost of Emotion's dynamic styling
- **Enhanced Theming**: System and brand tokens provide semantic, themeable values
- **Cross-Platform Consistency**: Single source of truth for design tokens across web, iOS, and
  Android
- **Future-Proofing**: Aligns with modern CSS capabilities and Canvas Kit's long-term direction

## LLM Assisted Migration <AIIndicator />

We provide a **LLM migration mapping file** (`llm-token-migration.txt`) specifically designed for
use with LLM-based code assistants (such as [Cursor](https://www.cursor.so/) or similar tools). This
file is not intended for direct human reference or team documentation, but rather as structured
input for LLMs to automate and assist with your token migration process.

> The LLM migration file is regularly updated to reflect the latest token mappings and best
> practices.
> For more details, see other sections of this migration guide.

This file contains a comprehensive mapping of old Canvas Kit token usages to their new equivalents
in `@workday/canvas-tokens-web`, along with migration tips and examples and formatted for optimal
LLM consumption.

**How to use:**

- **View raw file**: Open the file in a new tab to see the complete migration mapping
- **Download as txt**: Save the file locally to upload or paste into your LLM/code assistant
- **Use with LLM**: Provide the raw content to your LLM/code assistant as context for automated
  migration

<DownloadLLMFile
  rawFileLink="https://raw.githubusercontent.com/Workday/canvas-kit/master/modules/docs/llm-txt/llm-token-migration.txt"
  filename="llm-token-migration-13.2.0.txt"
/>

## Core Principles

### Token Hierarchy

The new token system is organized into three categories:

- **Base Tokens**: Fundamental values (colors, measurements) - use sparingly
- **System Tokens**: Semantic, themeable values - **use these in most cases**
- **Brand Tokens**: Tenant/brand-specific customization values

### CSS Variables Requirement

Unlike the old JavaScript tokens, the new tokens are CSS variables that must be wrapped in `var()`
for the browser to understand them.

**The Fundamental Change**: Raw (hex, px, etc) values → CSS variables wrapped in `var()`

```javascript
// Old approach - Raw values
import {space} from '@workday/canvas-kit-react/tokens';
// padding: '1rem'
const styles = {padding: space.s};

// New approach - CSS variables with var()
import {system} from '@workday/canvas-tokens-web';
// padding: 'var(--cnvs-sys-space-x4)'
const styles = {padding: `var(${system.space.x4})`};

// New approach - Using cssVar utility (recommended) and fallback
import {cssVar} from '@workday/canvas-kit-styling';
// padding: 'var(--cnvs-sys-space-x4, 1rem)'
const styles = {padding: cssVar(system.space.x4, '1rem')};
```

### Styling Utilities

Canvas Kit provides styling utilities such as `createStyles`, `createStencil`, `cssVar`, and calc
functions to handle CSS variable syntax automatically.

<StorybookInformationHighlight
  title="Why use styling utilities?"
  description="Styling utilities automatically wrap tokens in <code>var()</code> and provide fallbacks for better browser support. They also ensure consistent token usage across your components."
  link="/?path=/docs/styling-getting-started-overview--docs"
  linkText="Learn more about styling utilities"
/>

## Best Practices

<br />

### Prefer System Tokens

Use system tokens over base tokens whenever possible for better theming support:

```javascript
// Good - Semantic and themeable
backgroundColor: system.color.bg.default;

// Avoid - Hard-coded base value
backgroundColor: base.frenchVanilla100;
```

### Use Complete Type Levels

Instead of mixing individual type properties, use complete type level tokens:

```javascript
// Good - Consistent type styling
...system.type.body.medium

// Avoid - Mixing individual properties
fontSize: system.fontSize.body.medium,
fontWeight: system.fontWeight.regular,
lineHeight: '1.5'
```

### Leverage Styling Utilities

Always use `createStyles` and `cssVar` for proper CSS variable handling:

```javascript
// Good - Proper CSS variable wrapping
const styles = createStyles({
  padding: system.space.x4,
});

// Avoid - Manual CSS variable handling
const styles = {
  padding: `var(${system.space.x4})`,
};
```

### Convert Pixel Values

Use `px2rem` for pixel-based values to maintain consistency:

```javascript
import {px2rem} from '@workday/canvas-kit-styling';

const styles = createStyles({
  border: `solid ${px2rem(1)}`,
  borderColor: system.color.border.container,
});
```