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

Documentation components of Canvas Kit components

# Q&A and more

## Common Pitfalls & Solutions

### Forgetting CSS Variable Imports

**Problem**: Styles don't apply because CSS variables aren't defined. **Solution**: Ensure you've
imported the CSS variable files at your app's top level.

### Not Using var() Wrapper

**Problem**: CSS properties don't work with raw token values. **Solution**: Use `createStyles` or
`cssVar` utility instead of direct token references.

### Mixing Old and New Tokens

**Problem**: Inconsistent styling and potential conflicts. **Solution**: Migrate completely to new
tokens rather than mixing systems.

### Using Base Tokens for Everything

**Problem**: Missing out on theming capabilities. **Solution**: Prefer system tokens for their
semantic meaning and theming support.

## Incremental Migration Strategy

1. **Start with New Projects**: Use new tokens for all new components and features
2. **Component-by-Component**: Migrate existing components one at a time
3. **Test Thoroughly**: Ensure visual consistency after each component migration
4. **Update Style Patterns**: Migrate from style props to `createStyles` where needed
5. **Consolidate Imports**: Remove old token imports once migration is complete

## Complete Migration Examples

<br />

### Example 1: Card Component Migration

#### Before (Old Tokens)

```javascript
import {borderRadius, colors, depth, space, type} from '@workday/canvas-kit-react/tokens';
import {createStyles} from '@workday/canvas-kit-styling';

const cardStyles = createStyles({
  padding: space.l,
  backgroundColor: colors.frenchVanilla100,
  borderColor: colors.soap500,
  borderRadius: borderRadius.m,
  color: colors.blackPepper300,
  depth: 1,
  ...type.levels.body.medium,
});

const headerStyles = createStyles({
  color: colors.blackPepper500,
  marginBottom: space.s,
  ...type.levels.heading.small,
});

const errorTextStyles = createStyles({
  color: colors.cinnamon500,
  ...type.levels.subtext.large,
});
```

#### After (New Tokens - Semantic System Approach)

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

const cardStyles = createStyles({
  padding: system.padding.xxl,
  backgroundColor: system.color.surface.default,
  border: `solid ${px2rem(1)}`,
  borderColor: system.color.border.strong,
  borderRadius: system.shape.sm,
  color: system.color.fg.default,
  boxShadow: system.depth[1],
  ...system.type.body.md,
});

const headerStyles = createStyles({
  color: system.color.fg.default,
  marginBlockEnd: system.gap.md,
  ...system.type.heading.sm,
});

const errorTextStyles = createStyles({
  color: system.color.fg.danger.default,
  ...system.type.subtext.lg,
});
```

### Example 2: Form Input Migration

#### Before (Old Tokens)

```javascript
import {borderRadius, colors, space} from '@workday/canvas-kit-react/tokens';
import {createStyles} from '@workday/canvas-kit-styling';

const inputStyles = createStyles({
  padding: `${space.xs} ${space.s}`,
  backgroundColor: colors.frenchVanilla100,
  borderColor: colors.soap400,
  borderRadius: borderRadius.s,
  color: colors.blackPepper400,
  '&:focus': {
    borderColor: colors.blueberry400,
    backgroundColor: colors.frenchVanilla100,
  },
  '&.error': {
    borderColor: colors.cinnamon500,
    backgroundColor: colors.cinnamon100,
  },
  '&:disabled': {
    backgroundColor: colors.soap200,
    color: colors.soap600,
  },
});
```

#### After (New Tokens - System Approach)

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

const inputStyles = createStyles({
  padding: `${system.padding.sm} ${system.padding.md}`,
  backgroundColor: system.color.surface.default,
  borderColor: system.color.border.default,
  borderRadius: px2rem(2),
  color: system.color.fg.default,
  '&:focus': {
    borderColor: system.color.border.primary.default,
    backgroundColor: system.color.surface.default,
  },
  '&.error': {
    borderColor: system.color.border.critical.default,
    backgroundColor: system.color.surface.critical.default,
  },
  '&:disabled': {
    backgroundColor: system.color.surface.raised,
    color: system.color.fg.disabled,
  },
});
```

### Example 3: Button Migration with Brand Colors

#### Before (Old Tokens)

```javascript
import {theme} from '@emotion/react';

import {borderRadius, colors, space} from '@workday/canvas-kit-react/tokens';
import {createStyles} from '@workday/canvas-kit-styling';

const primaryButtonStyles = createStyles({
  padding: `${space.xs} ${space.m}`,
  backgroundColor: theme.canvas.palette.primary.main,
  borderColor: theme.canvas.palette.primary.main,
  borderRadius: borderRadius.m,
  color: theme.canvas.palette.primary.contrast,
  '&:hover': {
    backgroundColor: theme.canvas.palette.primary.dark,
  },
});
```

#### After (New Tokens - Brand + System)

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

const primaryButtonStyles = createStyles({
  padding: `${system.padding.sm} ${system.padding.xl}`,
  backgroundColor: brand.primary600,
  borderColor: brand.common.focus,
  borderRadius: system.shape.sm,
  color: system.color.fg.inverse,
  '&:hover': {
    backgroundColor: brand.primary800,
  },
});
```

## Next Steps

After completing the token migration:

- Review your components for consistent use of system tokens
- Consider implementing theming if not already in place
- Update your team's coding standards to reflect new token usage
- Monitor for any visual regressions and address them promptly

## Resources

- [Canvas Tokens Documentation](https://canvas.workday.com/styles/tokens/)
- [Canvas Tokens v3 Upgrade Guide](https://workday.github.io/canvas-tokens/?path=/docs/guides-upgrade-guides-v3-overview--docs)
- [Canvas Kit Styling Documentation](https://workday.github.io/canvas-kit/?path=/docs/styling-getting-started-overview--docs)
- [Token Migration Discussion](https://github.com/Workday/canvas-tokens/discussions/77)
- [Canvas Kit GitHub Repository](https://github.com/Workday/canvas-kit)