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

Documentation components of Canvas Kit components

import {DownloadLLMFile, StorybookStatusIndicator} from '@workday/canvas-kit-docs';

import {StorybookInformationHighlight} from './StorybookInformationHighlight';


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

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`. Canvas Kit
is using tokens from `@workday/canvas-tokens-web` v4 that introduced significant updates to align
with our Design Refresh, providing enhanced scalability, better product support, and a more
comprehensive token system. This release focuses on improving the color system with extended alpha
scales, updating brand tokens to use numerical naming conventions, and introducing new surface,
focus, accent, and semantic tokens.

## 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 <StorybookStatusIndicator type="ai" />

<StorybookInformationHighlight
  title="Note: Looking for an easier path to migrate?"
  description="We recommend using the Canvas Kit MCP"
  link="/?path=/docs/ai-for-llms-mcp-docs--docs"
  linkText="Learn more about the Canvas Kit MCP"
/>

## 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 - Using cssVar utility (recommended) and fallback
import {cssVar} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';
// padding: 'var(--cnvs-sys-padding-md, 1rem)'
const styles = {padding: cssVar(system.padding.md, '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.surface.default;

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

### Use Complete Type Levels

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

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

// Avoid - Mixing individual properties
fontSize: system.fontSize.body.md,
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.padding.md,
});

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

### Convert Pixel Values

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

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

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