Canvas Kit Token Migration Guide: Moving to @workday/canvas-tokens-web
================================================================================
IMPORTANT: This migration guide is for Canvas Kit v14 (historical)
================================================================================
For the current v4.4 token surface (Sana Canvas, t-shirt scales, deprecations), see
tokens/v4/v4.4-token-reference.md in this MCP server's token documentation.
Canvas Kit v14 is using 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. This migration enables better theming capabilities,
improved performance, and a more standardized approach to styling across the Canvas
design system.
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
Core Principles
===============
1. 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
2. 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.
3. Styling Utilities
Use Canvas Kit's styling utilities (createStyles, cssVar) to ensure proper CSS
variable handling.
Installation & Setup
====================
1. Install the New Package
```
npm install @workday/canvas-tokens-web
# or
yarn add @workday/canvas-tokens-web
```
2. Import CSS Variables
Import the variables at the top level of your application:
In a CSS file:
```
@import '@workday/canvas-tokens-web/css/base/_variables.css';
@import '@workday/canvas-tokens-web/css/system/_variables.css';
@import '@workday/canvas-tokens-web/css/brand/_variables.css';
import '@workday/canvas-tokens-web/css/component/_variables.css';
```
In a JavaScript/TypeScript file:
```
import '@workday/canvas-tokens-web/css/base/_variables.css';
import '@workday/canvas-tokens-web/css/system/_variables.css';
import '@workday/canvas-tokens-web/css/brand/_variables.css';
import '@workday/canvas-tokens-web/css/component/_variables.css';
```
3. Update Styling Approach
If you're not already using createStyles, migrate from style props to the styling utilities:
```
import { createStyles, cssVar } from '@workday/canvas-kit-styling';
import { system } from '@workday/canvas-tokens-web';
```
Migration Patterns
==================
Using CSS Variables
The Fundamental Change: JavaScript values → CSS variables wrapped in var()
```
// Old approach - JavaScript values
import { space } from '@workday/canvas-kit-react/tokens';
const styles = { padding: space.s };
// New approach - CSS variables with var()
import { system } from '@workday/canvas-tokens-web';
const styles = { padding: `var(${system.space.x4})` };
// New approach - Using cssVar utility (recommended)
import { cssVar } from '@workday/canvas-kit-styling';
const styles = { padding: cssVar(system.space.x4) };
```
Color Token Migration
=====================
Base Color Mapping (1:1 Direct Replacement)
Base colors have a direct 1:1 mapping - simply replace colors with base:
| Old Token | New Token | CSS Variable | System Color Replacement |
| ------------------------------ | --------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `colors.cinnamon100` | `base.red50` | `--cnvs-base-palette-red-50` | sys.color.bg.critical.softer |
| `colors.cinnamon200` | `base.red100` | `--cnvs-base-palette-red-100` | sys.color.bg.critical.soft |
| `colors.cinnamon300` | `base.red300` | `--cnvs-base-palette-red-300` | |
| `colors.cinnamon400` | `base.red400` | `--cnvs-base-palette-red-400` | sys.color.fg.critical.soft |
| `colors.cinnamon500` | `base.red600` | `--cnvs-base-palette-red-600` | sys.color.bg.critical.default
sys.color.fg.critical.default
sys.color.border.critical.default |
| `colors.cinnamon600` | `base.red700` | `--cnvs-base-palette-red-700` | sys.color.bg.critical.strong
sys.color.fg.critical.strong |
| `colors.peach100` | `base.coral50` | `--cnvs-base-palette-coral-50` | |
| `colors.peach200` | `base.coral200` | `--cnvs-base-palette-coral-200` | |
| `colors.peach300` | `base.coral300` | `--cnvs-base-palette-coral-300` | |
| `colors.peach400` | `base.coral400` | `--cnvs-base-palette-coral-400` | |
| `colors.peach500` | `base.coral600` | `--cnvs-base-palette-coral-600` | |
| `colors.peach600` | `base.coral700` | `--cnvs-base-palette-coral-700` | |
| `colors.chiliMango100` | `base.coral100` | `--cnvs-base-palette-coral-100` | |
| `colors.chiliMango200` | `base.coral200` | `--cnvs-base-palette-coral-200` | |
| `colors.chiliMango300` | `base.coral300` | `--cnvs-base-palette-coral-300` | |
| `colors.chiliMango400` | `base.coral500` | `--cnvs-base-palette-coral-500` | |
| `colors.chiliMango500` | `base.coral500` | `--cnvs-base-palette-coral-500` | |
| `colors.chiliMango600` | `base.coral700` | `--cnvs-base-palette-coral-700` | |
| `colors.cantaloupe100` | `base.amber50` | `--cnvs-base-palette-amber-50` | sys.color.bg.caution.softer |
| `colors.cantaloupe200` | `base.amber200` | `--cnvs-base-palette-amber-200` | sys.color.bg.caution.soft |
| `colors.cantaloupe300` | `base.amber300` | `--cnvs-base-palette-amber-300` | |
| `colors.cantaloupe400` | `base.amber400` | `--cnvs-base-palette-amber-400` | sys.color.bg.caution.default
sys.color.border.caution.default |
| `colors.cantaloupe500` | `base.amber500` | `--cnvs-base-palette-amber-500` | sys.color.bg.caution.strong
sys.color.fg.caution.softer |
| `colors.cantaloupe600` | `base.amber600` | `--cnvs-base-palette-amber-600` | sys.color.bg.caution.stronger
sys.color.border.caution.strong |
| `colors.sourLemon100` | `base.amber25` | `--cnvs-base-palette-amber-25` | |
| `colors.sourLemon200` | `base.amber100` | `--cnvs-base-palette-amber-100` | |
| `colors.sourLemon300` | `base.amber200` | `--cnvs-base-palette-amber-200` | |
| `colors.sourLemon400` | `base.amber300` | `--cnvs-base-palette-amber-300` | |
| `colors.sourLemon500` | `base.amber300` | `--cnvs-base-palette-amber-300` | |
| `colors.sourLemon600` | `base.amber500` | `--cnvs-base-palette-amber-500` | |
| `colors.juicyPear100` | `base.amber25` | `--cnvs-base-palette-amber-25` | |
| `colors.juicyPear200` | `base.amber100` | `--cnvs-base-palette-amber-100` | |
| `colors.juicyPear300` | `base.amber200` | `--cnvs-base-palette-amber-200` | |
| `colors.juicyPear400` | `base.amber200` | `--cnvs-base-palette-amber-200` | |
| `colors.juicyPear500` | `base.green500` | `--cnvs-base-palette-green-500` | |
| `colors.juicyPear600` | `base.green700` | `--cnvs-base-palette-green-700` | |
| `colors.kiwi100` | `base.green50` | `--cnvs-base-palette-green-50` | |
| `colors.kiwi200` | `base.green100` | `--cnvs-base-palette-green-100` | |
| `colors.kiwi300` | `base.green200` | `--cnvs-base-palette-green-200` | |
| `colors.kiwi400` | `base.green500` | `--cnvs-base-palette-green-500` | |
| `colors.kiwi500` | `base.green500` | `--cnvs-base-palette-green-500` | |
| `colors.kiwi600` | `base.green700` | `--cnvs-base-palette-green-700` | |
| `colors.greenApple50` | `base.green50` | `--cnvs-base-palette-green-50` | sys.color.bg.positive.softer |
| `colors.greenApple100` | `base.green100` | `--cnvs-base-palette-green-100` | sys.color.bg.positive.soft |
| `colors.greenApple200` | `base.green200` | `--cnvs-base-palette-green-200` | sys.color.fg.positive.soft |
| `colors.greenApple600` | `base.green600` | `--cnvs-base-palette-green-600` | sys.color.bg.positive.default
sys.color.fg.positive.default |
| `colors.greenApple700` | `base.green700` | `--cnvs-base-palette-green-700` | sys.color.bg.positive.strong
sys.color.fg.positive.strong |
| `colors.greenApple800` | `base.green800` | `--cnvs-base-palette-green-800` | sys.color.bg.positive.stronger
sys.color.fg.positive.stronger |
| `colors.watermelon100` | `base.teal25` | `--cnvs-base-palette-teal-25` | |
| `colors.watermelon200` | `base.teal100` | `--cnvs-base-palette-teal-100` | |
| `colors.watermelon300` | `base.green100` | `--cnvs-base-palette-green-100` | |
| `colors.watermelon400` | `base.green600` | `--cnvs-base-palette-green-600` | |
| `colors.watermelon500` | `base.green700` | `--cnvs-base-palette-green-700` | |
| `colors.watermelon600` | `base.green900` | `--cnvs-base-palette-green-900` | |
| `colors.jewel100` | `base.teal25` | `--cnvs-base-palette-teal-25` | |
| `colors.jewel200` | `base.teal200` | `--cnvs-base-palette-teal-200` | |
| `colors.jewel300` | `base.teal400` | `--cnvs-base-palette-teal-400` | |
| `colors.jewel400` | `base.teal500` | `--cnvs-base-palette-teal-500` | |
| `colors.jewel500` | `base.teal600` | `--cnvs-base-palette-teal-600` | |
| `colors.jewel600` | `base.teal700` | `--cnvs-base-palette-teal-700` | |
| `colors.toothpaste100` | `base.azure50` | `--cnvs-base-palette-azure-50` | |
| `colors.toothpaste200` | `base.azure200` | `--cnvs-base-palette-azure-200` | |
| `colors.toothpaste300` | `base.azure300` | `--cnvs-base-palette-azure-300` | |
| `colors.toothpaste400` | `base.azure500` | `--cnvs-base-palette-azure-500` | |
| `colors.toothpaste500` | `base.azure700` | `--cnvs-base-palette-azure-700` | |
| `colors.toothpaste600` | `base.azure800` | `--cnvs-base-palette-azure-800` | |
| `colors.blueberry100` | `base.blue100` | `--cnvs-base-palette-blue-100` | |
| `colors.blueberry200` | `base.blue100` | `--cnvs-base-palette-blue-100` | sys.color.bg.primary.soft |
| `colors.blueberry300` | `base.blue400` | `--cnvs-base-palette-blue-400` | sys.color.fg.primary.soft |
| `colors.blueberry400` | `base.blue600` | `--cnvs-base-palette-blue-600` | sys.color.bg.primary.default
sys.color.fg.primary.default
sys.color.border.primary.default |
| `colors.blueberry500` | `base.blue700` | `--cnvs-base-palette-blue-700` | sys.color.bg.primary.strong
sys.color.fg.primary.strong |
| `colors.blueberry600` | `base.blue800` | `--cnvs-base-palette-blue-800` | sys.color.bg.primary.stronger
sys.color.text.primary.stronger |
| `colors.plum100` | `base.blue100` | `--cnvs-base-palette-blue-100` | |
| `colors.plum200` | `base.blue200` | `--cnvs-base-palette-blue-200` | |
| `colors.plum300` | `base.blue300` | `--cnvs-base-palette-blue-300` | |
| `colors.plum400` | `base.blue400` | `--cnvs-base-palette-blue-400` | |
| `colors.plum500` | `base.blue500` | `--cnvs-base-palette-blue-500` | |
| `colors.plum600` | `base.blue600` | `--cnvs-base-palette-blue-600` | |
| `colors.berrySmoothie100` | `base.indigo50` | `--cnvs-base-palette-indigo-50` | |
| `colors.berrySmoothie200` | `base.indigo200` | `--cnvs-base-palette-indigo-200` | |
| `colors.berrySmoothie300` | `base.indigo400` | `--cnvs-base-palette-indigo-400` | |
| `colors.berrySmoothie400` | `base.blue500` | `--cnvs-base-palette-blue-500` | |
| `colors.berrySmoothie500` | `base.blue700` | `--cnvs-base-palette-blue-700` | |
| `colors.berrySmoothie600` | `base.blue800` | `--cnvs-base-palette-blue-800` | |
| `colors.blackberry100` | `base.indigo25` | `--cnvs-base-palette-indigo-25` | |
| `colors.blackberry200` | `base.indigo200` | `--cnvs-base-palette-indigo-200` | |
| `colors.blackberry300` | `base.indigo400` | `--cnvs-base-palette-indigo-400` | |
| `colors.blackberry400` | `base.indigo500` | `--cnvs-base-palette-indigo-500` | |
| `colors.blackberry500` | `base.indigo700` | `--cnvs-base-palette-indigo-700` | |
| `colors.blackberry600` | `base.indigo900` | `--cnvs-base-palette-indigo-900` | |
| `colors.islandPunch100` | `base.purple25` | `--cnvs-base-palette-purple-25` | |
| `colors.islandPunch200` | `base.purple200` | `--cnvs-base-palette-purple-200` | |
| `colors.islandPunch300` | `base.purple500` | `--cnvs-base-palette-purple-500` | |
| `colors.islandPunch400` | `base.purple500` | `--cnvs-base-palette-purple-500` | |
| `colors.islandPunch500` | `base.purple700` | `--cnvs-base-palette-purple-700` | |
| `colors.islandPunch600` | `base.purple800` | `--cnvs-base-palette-purple-800` | |
| `colors.grapeSoda100` | `base.magenta50` | `--cnvs-base-palette-magenta-50` | |
| `colors.grapeSoda200` | `base.magenta200` | `--cnvs-base-palette-magenta-200` | |
| `colors.grapeSoda300` | `base.purple400` | `--cnvs-base-palette-purple-400` | |
| `colors.grapeSoda400` | `base.purple500` | `--cnvs-base-palette-purple-500` | |
| `colors.grapeSoda500` | `base.purple600` | `--cnvs-base-palette-purple-600` | |
| `colors.grapeSoda600` | `base.purple800` | `--cnvs-base-palette-purple-800` | |
| `colors.pomegranate100` | `base.magenta50` | `--cnvs-base-palette-magenta-50` | |
| `colors.pomegranate200` | `base.magenta100` | `--cnvs-base-palette-magenta-100` | |
| `colors.pomegranate300` | `base.magenta500` | `--cnvs-base-palette-magenta-500` | |
| `colors.pomegranate400` | `base.magenta400` | `--cnvs-base-palette-magenta-400` | |
| `colors.pomegranate500` | `base.red700` | `--cnvs-base-palette-red-700` | |
| `colors.pomegranate600` | `base.red800` | `--cnvs-base-palette-red-800` | |
| `colors.fruitPunch100` | `base.red25` | `--cnvs-base-palette-red-25` | |
| `colors.fruitPunch200` | `base.red200` | `--cnvs-base-palette-red-200` | |
| `colors.fruitPunch300` | `base.red300` | `--cnvs-base-palette-red-300` | |
| `colors.fruitPunch400` | `base.red400` | `--cnvs-base-palette-red-400` | |
| `colors.fruitPunch500` | `base.red400` | `--cnvs-base-palette-red-400` | |
| `colors.fruitPunch600` | `base.red700` | `--cnvs-base-palette-red-700` | |
| `colors.rootBeer100` | `base.coral25` | `--cnvs-base-palette-coral-25` | |
| `colors.rootBeer200` | `base.coral100` | `--cnvs-base-palette-coral-100` | |
| `colors.rootBeer300` | `base.coral200` | `--cnvs-base-palette-coral-200` | |
| `colors.rootBeer400` | `base.coral200` | `--cnvs-base-palette-coral-200` | |
| `colors.rootBeer500` | `base.amber900` | `--cnvs-base-palette-amber-900` | |
| `colors.rootBeer600` | `base.amber950` | `--cnvs-base-palette-amber-950` | |
| `colors.toastedMarshmallow100` | `base.amber25` | `--cnvs-base-palette-amber-25` | |
| `colors.toastedMarshmallow200` | `base.orange100` | `--cnvs-base-palette-orange-100` | |
| `colors.toastedMarshmallow300` | `base.orange200` | `--cnvs-base-palette-orange-200` | |
| `colors.toastedMarshmallow400` | `base.orange300` | `--cnvs-base-palette-orange-300` | |
| `colors.toastedMarshmallow500` | `base.amber500` | `--cnvs-base-palette-amber-500` | |
| `colors.toastedMarshmallow600` | `base.amber600` | `--cnvs-base-palette-amber-600` | |
| `colors.licorice100` | `base.slate400` | `--cnvs-base-palette-slate-400` | sys.color.bg.muted.softer
sys.color.fg.disabled
sys.color.border.input.disabled |
| `colors.licorice200` | `base.slate500` | `--cnvs-base-palette-slate-500` | sys.color.bg.muted.soft
sys.color.fg.muted.soft
sys.color.border.input.default |
| `colors.licorice300` | `base.slate600` | `--cnvs-base-palette-slate-600` | sys.color.bg.muted.default
sys.color.fg.muted.default
sys.color.text.hint |
| `colors.licorice400` | `base.slate700` | `--cnvs-base-palette-slate-700` | sys.color.fg.muted.strong |
| `colors.licorice500` | `base.slate800` | `--cnvs-base-palette-slate-800` | sys.color.bg.muted.strong
sys.color.fg.muted.stronger
sys.color.border.input.strong |
| `colors.licorice600` | `base.slate900` | `--cnvs-base-palette-slate-900` | |
| `colors.blackPepper100` | `base.neutral500` | `--cnvs-base-palette-neutral-500` | |
| `colors.blackPepper200` | `base.neutral700` | `--cnvs-base-palette-neutral-700` | |
| `colors.blackPepper300` | `base.neutral900` | `--cnvs-base-palette-neutral-900` | sys.color.fg.default |
| `colors.blackPepper400` | `base.neutral950` | `--cnvs-base-palette-neutral-950` | sys.color.bg.contrast.default
sys.color.fg.strong
sys.color.border.contrast.default |
| `colors.blackPepper500` | `base.neutral975` | `--cnvs-base-palette-neutral-975` | sys.color.bg.contrast.strong
sys.color.fg.stronger
sys.color.border.contrast.strong |
| `colors.blackPepper600` | `base.neutral1000` | `--cnvs-base-palette-neutral-1000` | |
| `colors.frenchVanilla100` | `base.neutral0` | `--cnvs-base-palette-neutral-0` | sys.color.bg.default
sys.color.fg.inverse
sys.color.border.inverse |
| `colors.frenchVanilla200` | `base.neutral100` | `--cnvs-base-palette-neutral-100` | |
| `colors.frenchVanilla300` | `base.neutral200` | `--cnvs-base-palette-neutral-200` | |
| `colors.frenchVanilla400` | `base.neutral300` | `--cnvs-base-palette-neutral-300` | |
| `colors.frenchVanilla500` | `base.neutral400` | `--cnvs-base-palette-neutral-400` | |
| `colors.frenchVanilla600` | `base.neutral500` | `--cnvs-base-palette-neutral-500` | |
| `colors.soap100` | `base.slate25` | `--cnvs-base-palette-slate-25` | sys.color.bg.alt.softer |
| `colors.soap200` | `base.slate50` | `--cnvs-base-palette-slate-50` | sys.color.bg.alt.soft |
| `colors.soap300` | `base.slate100` | `--cnvs-base-palette-slate-100` | sys.color.bg.alt.default
sys.color.border.input.inverse |
| `colors.soap400` | `base.slate200` | `--cnvs-base-palette-slate-200` | sys.color.bg.alt.strong
sys.color.border.divider |
| `colors.soap500` | `base.slate300` | `--cnvs-base-palette-slate-300` | sys.color.bg.alt.stronger
sys.color.border.container |
| `colors.soap600` | `base.slate300` | `--cnvs-base-palette-slate-300` | |
| `colors.coconut100` | `base.coconut100` (deprecated) | `--cnvs-base-palette-coconut-100` | |
| `colors.coconut200` | `base.coconut200` (deprecated) | `--cnvs-base-palette-coconut-200` | |
| `colors.coconut300` | `base.coconut300` (deprecated) | `--cnvs-base-palette-coconut-300` | |
| `colors.coconut400` | `base.coconut400` (deprecated) | `--cnvs-base-palette-coconut-400` | |
| `colors.coconut500` | `base.coconut500` (deprecated) | `--cnvs-base-palette-coconut-500` | |
| `colors.coconut600` | `base.coconut600` (deprecated) | `--cnvs-base-palette-coconut-600` | |
| `colors.cappuccino100` | `base.cappuccino100` (deprecated) | `--cnvs-base-palette-cappuccino-100` | |
| `colors.cappuccino200` | `base.cappuccino200` (deprecated) | `--cnvs-base-palette-cappuccino-200` | |
| `colors.cappuccino300` | `base.cappuccino300` (deprecated) | `--cnvs-base-palette-cappuccino-300` | |
| `colors.cappuccino400` | `base.cappuccino400` (deprecated) | `--cnvs-base-palette-cappuccino-400` | |
| `colors.cappuccino500` | `base.cappuccino500` (deprecated) | `--cnvs-base-palette-cappuccino-500` | |
| `colors.cappuccino600` | `base.cappuccino600` (deprecated) | `--cnvs-base-palette-cappuccino-600` | |
| `colors.dragonFruit100` | `base.purple25` | `--cnvs-base-palette-purple-25` | |
| `colors.dragonFruit200` | `base.purple100` | `--cnvs-base-palette-purple-100` | |
| `colors.dragonFruit300` | `base.indigo500` | `--cnvs-base-palette-indigo-500` | |
| `colors.dragonFruit400` | `base.indigo600` | `--cnvs-base-palette-indigo-600` | |
| `colors.dragonFruit500` | `base.indigo700` | `--cnvs-base-palette-indigo-700` | |
| `colors.dragonFruit600` | `base.indigo800` | `--cnvs-base-palette-indigo-800` | |
Brand Color Migration
Brand colors move from the Emotion theme object to direct CSS variables:
Old Token | New Token | CSS Variable
-------------------------------------------|-----------------------------|---------------------------------
theme.canvas.palette.primary.lightest | brand.primary.lightest | --cnvs-brand-primary-lightest
theme.canvas.palette.primary.light | brand.primary.light | --cnvs-brand-primary-light
theme.canvas.palette.primary.main | brand.primary.base | --cnvs-brand-primary-base
theme.canvas.palette.primary.dark | brand.primary.dark | --cnvs-brand-primary-dark
theme.canvas.palette.primary.darkest | brand.primary.darkest | --cnvs-brand-primary-darkest
theme.canvas.palette.primary.contrast | brand.primary.accent | --cnvs-brand-primary-accent
theme.canvas.palette.error.lightest | brand.error.lightest | --cnvs-brand-error-lightest
theme.canvas.palette.error.light | brand.error.light | --cnvs-brand-error-light
theme.canvas.palette.error.main | brand.error.base | --cnvs-brand-error-base
theme.canvas.palette.error.dark | brand.error.dark | --cnvs-brand-error-dark
theme.canvas.palette.error.darkest | brand.error.darkest | --cnvs-brand-error-darkest
theme.canvas.palette.error.contrast | brand.error.accent | --cnvs-brand-error-accent
theme.canvas.palette.alert.lightest | brand.alert.lightest | --cnvs-brand-alert-lightest
theme.canvas.palette.alert.light | brand.alert.light | --cnvs-brand-alert-light
theme.canvas.palette.alert.main | brand.alert.base | --cnvs-brand-alert-base
theme.canvas.palette.alert.dark | brand.alert.dark | --cnvs-brand-alert-dark
theme.canvas.palette.alert.darkest | brand.alert.darkest | --cnvs-brand-alert-darkest
theme.canvas.palette.alert.contrast | brand.alert.accent | --cnvs-brand-alert-accent
theme.canvas.palette.success.lightest | brand.success.lightest | --cnvs-brand-success-lightest
theme.canvas.palette.success.light | brand.success.light | --cnvs-brand-success-light
theme.canvas.palette.success.main | brand.success.base | --cnvs-brand-success-base
theme.canvas.palette.success.dark | brand.success.dark | --cnvs-brand-success-dark
theme.canvas.palette.success.darkest | brand.success.darkest | --cnvs-brand-success-darkest
theme.canvas.palette.success.contrast | brand.success.accent | --cnvs-brand-success-accent
theme.canvas.palette.neutral.lightest | brand.neutral.lightest | --cnvs-brand-neutral-lightest
theme.canvas.palette.neutral.light | brand.neutral.light | --cnvs-brand-neutral-light
theme.canvas.palette.neutral.main | brand.neutral.base | --cnvs-brand-neutral-base
theme.canvas.palette.neutral.dark | brand.neutral.dark | --cnvs-brand-neutral-dark
theme.canvas.palette.neutral.darkest | brand.neutral.darkest | --cnvs-brand-neutral-darkest
theme.canvas.palette.neutral.contrast | brand.neutral.accent | --cnvs-brand-neutral-accent
theme.canvas.palette.common.focusOutline | brand.common.focusOutline | --cnvs-brand-common-focus-outline
System Color Usage Guide (Recommended)
System color tokens are organized into semantic "blocks" that represent their intended use in your
UI. Instead of referencing raw base colors, use these system tokens to ensure your application is
themeable, understandable, and consistent.
- Background (system.color.bg.*): For all surface and container backgrounds, including pages,
cards, banners, and input fields.
- Foreground (system.color.fg.*): For text and icon colors. Use variants for body text,
headings, links, disabled states, and inverse (light-on-dark) content.
- Border (system.color.border.*): For outlines, dividers, and input borders. Select the
variant that matches the required emphasis or interaction state.
+----------------------------------------+----------------------------------------+-----------------------------+----------------------------------------------+
| Use Case | System Token | Old Token(s) | Example Usage |
+----------------------------------------+----------------------------------------+-----------------------------+----------------------------------------------+
| **Background Colors** | | | |
| Main page background | system.color.bg.default | colors.frenchVanilla100 | Page layout base background |
| | | inputColors.background | |
| | | commonColors.background | |
| Disabled elements | system.color.bg.primary.soft | colors.blueberry200 | Disabled primary buttons |
| Brand default background | system.color.bg.primary.default | colors.blueberry400 | Brand banners, primary button background |
| | | commonColors.focusBackground| |
| | | inputColors.selectionControlFill | |
| Brand hover background | system.color.bg.primary.strong | colors.blueberry500 | Primary button hover |
| Brand active background | system.color.bg.primary.stronger | colors.blueberry600 | Primary button active |
| Warning subtle background | system.color.bg.caution.softer | colors.cantaloupe100 | Soft warning banners |
| Warning default background | system.color.bg.caution.default | colors.cantaloupe400 | Toast notifications |
| Warning hover background | system.color.bg.caution.strong | colors.cantaloupe500 | Warning hover states |
| Warning active background | system.color.bg.caution.stronger | colors.cantaloupe600 | Warning active states |
| Error disabled background | system.color.bg.critical.softer | colors.cinnamon100 | Disabled error button |
| Error default background | system.color.bg.critical.default | colors.cinnamon500 | Error message background |
| Error hover background | system.color.bg.critical.strong | colors.cinnamon600 | Delete button hover |
| Success surface background | system.color.bg.positive.softer | colors.greenApple100 | Cards showing success status |
| Success default background | system.color.bg.positive.default | colors.greenApple400 | Disabled success buttons |
| Success hover background | system.color.bg.positive.strong | colors.greenApple500 | Success button hover |
| Success active background | system.color.bg.positive.stronger | colors.greenApple600 | Success button active |
| Muted background (subtle) | system.color.bg.muted.softer | colors.licorice100 | Light containers |
| Muted background (soft) | system.color.bg.muted.soft | colors.licorice200 | Form backgrounds |
| Muted background (default) | system.color.bg.muted.default | colors.licorice300 | Input fields, inactive elements |
| Muted strong background | system.color.bg.muted.strong | colors.licorice500 | Switch toggles, loading indicators |
| Disabled input background | system.color.bg.alt.softer | colors.soap100 | Disabled text input fields |
| | | inputColors.disabled.background | |
| Alt page background | system.color.bg.alt.soft | colors.soap200 | Dashboard sections |
| Secondary surface background | system.color.bg.alt.default | colors.soap300 | Card hover background |
| | | commonColors.backgroundAlt | |
| Secondary hover background | system.color.bg.alt.strong | colors.soap400 | Hover state for modals |
| | | commonColors.hoverBackground| |
| Secondary active background | system.color.bg.alt.stronger | colors.soap500 | Clicked state for surfaces |
| Contrast background (default) | system.color.bg.contrast.default | colors.blackPepper400 | Tooltip background |
| Contrast background (strong) | system.color.bg.contrast.strong | colors.blackPepper500 | High-contrast text container background |
| **Foreground Colors (text and icons)** | | | |
| Body foreground | system.color.fg.default | colors.blackPepper300 | Paragraphs, regular content |
| | | typeColors.body | |
| | | typeColors.label | |
| | | inputColors.text | |
| Headings | system.color.fg.strong | colors.blackPepper400 | Section and card headings |
| | | typeColors.heading | |
| Display titles | system.color.fg.stronger | colors.blackPepper500 | Hero titles, large headings |
| Link foreground | system.color.fg.primary.default | colors.blueberry400 | Anchor links |
| | | iconColors.active | |
| | | statusColors.active | |
| | | typeColors.link | |
| | | typeColors.selectHighlight | |
| Link foreground hover | system.color.fg.primary.strong | colors.blueberry500 | Hover state for links |
| Error foreground | system.color.fg.critical.default | colors.cinnamon500 | Error messages |
| | | inputColors.error.icon | |
| | | statusColors.error | |
| Inverse (white) foreground | system.color.fg.inverse | colors.frenchVanilla100 | Text on dark backgrounds |
| | | typeColors.inverse | |
| | | typeColors.selectHighlightInverse | |
| | | iconColors.inverse | |
| Disabled foreground | system.color.fg.disabled | colors.licorice100 | Disabled buttons and form inputs |
| | | inputColors.disabled.text | |
| | | inputColors.disabled.icon | |
| | | iconColors.disabled | |
| Muted foreground (soft) | system.color.fg.muted.soft | colors.licorice200 | Tab labels, hint text |
| | | iconColors.standard | |
| | | inputColors.icon | |
| | | typeColors.hint | |
| Muted foreground (default) | system.color.fg.muted.default | colors.licorice300 | Subtitle or secondary text |
| | | inputColors.placeholder | |
| Muted foreground (strong) | system.color.fg.muted.strong | colors.licorice400 | Hover state for muted elements |
| Muted foreground (stronger) | system.color.fg.muted.stronger | colors.licorice500 | Active muted tabs text |
| | | iconColors.hover | |
| | | inputColors.iconHover | |
| **Border Colors** | | | |
| Contrast border | system.color.border.contrast.default | colors.blackPepper400 | Card outline, divider on light surfaces |
| Strong contrast border | system.color.border.contrast.strong | colors.blackPepper500 | High-contrast outlines or focus states |
| Primary active input border | system.color.border.primary.default | colors.blueberry400 | Active input fields |
| | | commonColors.focusOutline | |
| | | inputColors.focusBorder | |
| Warning border (inner) | system.color.border.caution.default | colors.cantaloupe400 | Alert field inner border |
| | | inputColors.alert.border | |
| | | statusColors.warning | |
| Warning border (outer) | system.color.border.caution.strong | colors.cantaloupe600 | Alert field box shadow |
| Error border | system.color.border.critical.default | colors.cinnamon500 | Form field with error |
| | | inputColors.error.border | |
| | | statusColors.error | |
| Inverse surface border | system.color.border.inverse | colors.frenchVanilla100 | Checkbox/radio on dark background |
| Disabled input border | system.color.border.input.disabled | colors.licorice100 | Non-editable input fields |
| Default input border | system.color.border.input.default | colors.licorice200 | Normal input field border |
| | | inputColors.border | |
| Hover input border | system.color.border.input.strong | colors.licorice500 | Input field on hover |
| | | inputColors.disabled.border | |
| Inverse input border | system.color.border.input.inverse | colors.soap300 | Inverse theme inputs |
| Divider/separator border | system.color.border.divider | colors.soap400 | Table rows, content separators |
| | | commonColors.divider | |
| Container border (card/table edge) | system.color.border.container | colors.soap500 | Card edge or section container border |
| **Static Colors** | | | |
| White | system.color.static.white | | Always white regardless of theme |
| Black | system.color.static.black | | Always black regardless of theme |
| Transparent | system.color.static.transparent | | Invisible backgrounds |
+----------------------------------------+----------------------------------------+-----------------------------+----------------------------------------------+
## Other Mapping
Certain old tokens have been deprecated without direct replacements. In these cases, we recommend
using the closest available base palette or gradient token references shown below rather than
semantic aliases; only use literal raw color values if no tokenized option exists.
### Gradients
Please note that the new gradients may appear visually different from the previous ones, as the
underlying base palette has been updated and the color mappings do not have exact equivalents.
| Gradient Name | Old Value | New Value |
| ------------------ | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| cinnamon | "linear-gradient(to bottom right," + colors.cinnamon500 + "," + colors.cinnamon400 + ")" | "linear-gradient(to bottom right, var(" + base.red600 + "), var(" + base.red400 + "))" |
| peach | "linear-gradient(to bottom right," + colors.peach500 + "," + colors.peach400 + ")" | "linear-gradient(to bottom right, var(" + base.coral600 + "), var(" + base.red400 + "))" |
| chiliMango | "linear-gradient(to bottom right," + colors.chiliMango500 + "," + colors.chiliMango400 + ")" | "linear-gradient(to bottom right, var(" + base.orange500 + "), var(" + base.orange400 + "))" |
| cantaloupe | "linear-gradient(to bottom right," + colors.cantaloupe500 + "," + colors.cantaloupe400 + ")" | "linear-gradient(to bottom right, var(" + base.amber500 + "), var(" + base.amber400 + "))" |
| sourLemon | "linear-gradient(to bottom right," + colors.sourLemon500 + "," + colors.sourLemon400 + ")" | "linear-gradient(to bottom right, var(" + base.amber300 + "), var(" + base.amber200 + "))" |
| juicyPear | "linear-gradient(to bottom right," + colors.juicyPear500 + "," + colors.juicyPear400 + ")" | "linear-gradient(to bottom right, var(" + base.green500 + "), var(" + base.green400 + "))" |
| kiwi | "linear-gradient(to bottom right," + colors.kiwi500 + "," + colors.kiwi400 + ")" | "linear-gradient(to bottom right, var(" + base.green500 + "), var(" + base.green400 + "))" |
| greenApple | "linear-gradient(to bottom right," + colors.greenApple500 + "," + colors.greenApple400 + ")" | "linear-gradient(to bottom right, var(" + base.green700 + "), var(" + base.green600 + "))" |
| watermelon | "linear-gradient(to bottom right," + colors.watermelon500 + "," + colors.watermelon400 + ")" | "linear-gradient(to bottom right, var(" + base.green700 + "), var(" + base.green600 + "))" |
| jewel | "linear-gradient(to bottom right," + colors.jewel500 + "," + colors.jewel400 + ")" | "linear-gradient(to bottom right, var(" + base.teal600 + "), var(" + base.teal500 + "))" |
| toothpaste | "linear-gradient(to bottom right," + colors.toothpaste500 + "," + colors.toothpaste400 + ")" | "linear-gradient(to bottom right, var(" + base.azure700 + "), var(" + base.azure500 + "))" |
| blueberry | "linear-gradient(to bottom right," + colors.blueberry500 + "," + colors.blueberry400 + ")" | `brand.gradient.primary` |
| plum | "linear-gradient(to bottom right," + colors.plum500 + "," + colors.plum400 + ")" | "linear-gradient(to bottom right, var(" + base.blue700 + "), var(" + base.blue600 + "))" |
| berrySmoothie | "linear-gradient(to bottom right," + colors.berrySmoothie500 + "," + colors.berrySmoothie400 + ")" | "linear-gradient(to bottom right, var(" + base.blue700 + "), var(" + base.blue500 + "))" |
| blackberry | "linear-gradient(to bottom right," + colors.blackberry500 + "," + colors.blackberry400 + ")" | "linear-gradient(to bottom right, var(" + base.indigo700 + "), var(" + base.indigo500 + "))" |
| islandPunch | "linear-gradient(to bottom right," + colors.islandPunch500 + "," + colors.islandPunch400 + ")" | "linear-gradient(to bottom right, var(" + base.purple700 + "), var(" + base.purple500 + "))" |
| grapeSoda | "linear-gradient(to bottom right," + colors.grapeSoda500 + "," + colors.grapeSoda400 + ")" | "linear-gradient(to bottom right, var(" + base.purple600 + "), var(" + base.purple500 + "))" |
| pomegranate | "linear-gradient(to bottom right," + colors.pomegranate500 + "," + colors.pomegranate400 + ")" | "linear-gradient(to bottom right, var(" + base.red700 + "), var(" + base.red600 + "))" |
| fruitPunch | "linear-gradient(to bottom right," + colors.fruitPunch500 + "," + colors.fruitPunch400 + ")" | "linear-gradient(to bottom right, var(" + base.red400 + "), var(" + base.red300 + "))" |
| rootBeer | "linear-gradient(to bottom right," + colors.rootBeer600 + "," + colors.rootBeer500 + ")" | "linear-gradient(to bottom right, var(" + base.amber950 + "), var(" + base.amber900 + "))" |
| toastedMarshmallow | "linear-gradient(to bottom right," + colors.toastedMarshmallow500 + "," + colors.toastedMarshmallow400 + ")" | "linear-gradient(to bottom right, var(" + base.amber500 + "), var(" + base.amber400 + "))" |
| cappuccino | "linear-gradient(to bottom right," + colors.cappuccino400 + "," + colors.cappuccino300 + ")" | "linear-gradient(to bottom right, var(" + base.amber500 + "), var(" + base.amber400 + "))" |
| licorice | "linear-gradient(to bottom right," + colors.licorice500 + "," + colors.licorice400 + ")" | "linear-gradient(to bottom right, var(" + base.slate800 + "), var(" + base.slate700 + "))" |
| blackPepper | "linear-gradient(to bottom right," + colors.blackPepper400 + "," + colors.blackPepper300 + ")" | "linear-gradient(to bottom right, var(" + base.neutral900 + "), var(" + base.neutral800 + "))" |
### Chart Colors
Please note that the new chart colors may appear visually different from the previous ones, as the
underlying base palette has been updated and the color mappings do not have exact equivalents.
| Old Token | Old Value | New Value |
| ----------------------------------- | ------------------------------ | ----------------- |
| `chartingColors[1]` | `colors.watermelon200` | `base.teal100` |
| `chartingColors[2]` | `colors.watermelon300` | `base.green100` |
| `chartingColors[3]` | `colors.jewel200` | `base.teal200` |
| `chartingColors[4]` | `colors.jewel300` | `base.teal400` |
| `chartingColors[5]` | `colors.plum200` | `base.blue200` |
| `chartingColors[6]` | `colors.plum300` | `base.blue400` |
| `chartingColors[7]` | `colors.islandPunch200` | `base.purple200` |
| `chartingColors[8]` | `colors.islandPunch300` | `base.purple500` |
| `chartingColors[9]` | `colors.pomegranate200` | `base.magenta100` |
| `chartingColors[10]` | `colors.pomegranate300` | `base.magenta500` |
| `chartingColors[11]` | `colors.peach200` | `base.coral200` |
| `chartingColors[12]` | `colors.peach400` | `base.coral300` |
| `chartingColors[13]` | `colors.cantaloupe200` | `base.amber200` |
| `chartingColors[14]` | `colors.cantaloupe400` | `base.amber300` |
| `chartingColors[15]` | `colors.sourLemon200` | `base.amber100` |
| `chartingColors[16]` | `colors.sourLemon400` | `base.amber200` |
| `chartingColors[17]` | `colors.watermelon400` | `base.green600` |
| `chartingColors[18]` | `colors.watermelon500` | `base.green700` |
| `chartingColors[19]` | `colors.jewel400` | `base.teal500` |
| `chartingColors[20]` | `colors.jewel500` | `base.teal600` |
| `chartingColors[21]` | `colors.plum400` | `base.blue600` |
| `chartingColors[22]` | `colors.plum500` | `base.blue700` |
| `chartingColors[23]` | `colors.islandPunch400` | `base.purple500` |
| `chartingColors[24]` | `colors.islandPunch500` | `base.purple600` |
| `chartingColors[25]` | `colors.pomegranate400` | `base.magenta500` |
| `chartingColors[26]` | `colors.pomegranate600` | `base.red700` |
| `chartingColors[27]` | `colors.peach500` | `base.coral600` |
| `chartingColors[28]` | `colors.peach600` | `base.coral700` |
| `chartingColors[29]` | `colors.cantaloupe500` | `base.amber500` |
| `chartingColors[30]` | `colors.cantaloupe600` | `base.amber600` |
| `chartingColors[31]` | `colors.sourLemon500` | `base.amber300` |
| `chartingColors[32]` | `colors.sourLemon600` | `base.amber500` |
| `chartingColors[33]` | `colors.greenApple200` | `base.green100` |
| `chartingColors[34]` | `colors.greenApple300` | `base.green200` |
| `chartingColors[35]` | `colors.toothpaste200` | `base.azure200` |
| `chartingColors[36]` | `colors.toothpaste300` | `base.azure300` |
| `chartingColors[37]` | `colors.blueberry200` | `base.blue100` |
| `chartingColors[38]` | `colors.blueberry300` | `base.blue400` |
| `chartingColors[39]` | `colors.berrySmoothie200` | `base.indigo200` |
| `chartingColors[40]` | `colors.blackberry300` | `base.indigo400` |
| `chartingColors[41]` | `colors.fruitPunch200` | `base.red200` |
| `chartingColors[42]` | `colors.fruitPunch300` | `base.red300` |
| `chartingColors[43]` | `colors.rootBeer200` | `base.coral100` |
| `chartingColors[44]` | `colors.rootBeer300` | `base.coral200` |
| `chartingColors[45]` | `colors.toastedMarshmallow200` | `base.orange100` |
| `chartingColors[46]` | `colors.toastedMarshmallow400` | `base.orange200` |
| `chartingColors[47]` | `colors.chiliMango200` | `base.coral200` |
| `chartingColors[48]` | `colors.chiliMango400` | `base.coral300` |
| `chartingColors[49]` | `colors.greenApple400` | `base.green600` |
| `chartingColors[50]` | `colors.greenApple600` | `base.green700` |
| `chartingColors[51]` | `colors.toothpaste400` | `base.azure500` |
| `chartingColors[52]` | `colors.toothpaste600` | `base.azure800` |
| `chartingColors[53]` | `colors.blueberry400` | `base.blue600` |
| `chartingColors[54]` | `colors.blueberry600` | `base.blue800` |
| `chartingColors[55]` | `colors.blackberry400` | `base.indigo500` |
| `chartingColors[56]` | `colors.blackberry600` | `base.indigo900` |
| `chartingColors[57]` | `colors.fruitPunch400` | `base.red400` |
| `chartingColors[58]` | `colors.fruitPunch600` | `base.red700` |
| `chartingColors[59]` | `colors.rootBeer500` | `base.amber900` |
| `chartingColors[60]` | `colors.rootBeer600` | `base.amber950` |
| `chartingColors[61]` | `colors.toastedMarshmallow500` | `base.amber500` |
| `chartingColors[62]` | `colors.toastedMarshmallow600` | `base.amber600` |
| `chartingColors[63]` | `colors.chiliMango500` | `base.orange500` |
| `chartingColors[64]` | `colors.chiliMango600` | `base.orange600` |
| `chartingColors[65]` | `colors.kiwi200` | `base.green100` |
| `chartingColors[66]` | `colors.kiwi400` | `base.green500` |
| `chartingColors[67]` | `colors.berrySmoothie200` | `base.indigo200` |
| `chartingColors[68]` | `colors.berrySmoothie300` | `base.indigo400` |
| `chartingColors[69]` | `colors.grapeSoda200` | `base.magenta200` |
| `chartingColors[70]` | `colors.grapeSoda300` | `base.magenta400` |
| `chartingColors[71]` | `colors.cinnamon200` | `base.red100` |
| `chartingColors[72]` | `colors.cinnamon300` | `base.red300` |
| `chartingColors[73]` | `colors.sourLemon300` | `base.amber200` |
| `chartingColors[74]` | `colors.toastedMarshmallow300` | `base.orange200` |
| `chartingColors[75]` | `colors.peach300` | `base.coral300` |
| `chartingColors[76]` | `colors.cinnamon500` | `base.red600` |
| `chartingColors[77]` | `colors.cantaloupe300` | `base.amber300` |
| `chartingColors[78]` | `colors.chiliMango300` | `base.coral300` |
| `chartingColors[79]` | `colors.kiwi300` | `base.green200` |
| `chartingColors[80]` | `colors.kiwi500` | `base.green500` |
| `chartingColors[81]` | `colors.berrySmoothie400` | `base.blue500` |
| `chartingColors[82]` | `colors.berrySmoothie500` | `base.blue700` |
| `chartingColors[83]` | `colors.grapeSoda400` | `base.purple500` |
| `chartingColors[84]` | `colors.grapeSoda500` | `base.purple600` |
| `chartingColors[85]` | `colors.cinnamon400` | `base.red400` |
| `chartingColors[86]` | `colors.cinnamon500` | `base.red600` |
| `chartingColorOffsets.barAndColumn` | `colors.watermelon200` | `base.teal100` |
| `chartingColorOffsets.pie` | `colors.jewel300` | `base.teal400` |
| `chartingColorOffsets.lineAndArea` | `colors.islandPunch200` | `base.purple200` |
| `chartingColorOffsets.bubble` | `colors.peach200` | `base.coral200` |
Migration Examples
==================
Example 1: Base Color Migration
```
// Old
import { colors } from '@workday/canvas-kit-react/tokens';
backgroundColor: colors.frenchVanilla100
// New (Direct mapping)
import { base } from '@workday/canvas-tokens-web';
backgroundColor: cssVar(base.neutral0)
```
Example 2: System Color Migration (Recommended)
```
// Old
import { colors } from '@workday/canvas-kit-react/tokens';
const styles = createStyles({
backgroundColor: colors.frenchVanilla100,
borderColor: colors.soap500,
color: colors.blackPepper300,
});
// New - Using semantic system tokens
import { system } from '@workday/canvas-tokens-web';
const styles = createStyles({
backgroundColor: system.color.bg.default,
borderColor: system.color.border.container,
color: system.color.text.default,
});
```
Example 3: Brand Color Migration
```
// Old
import { theme } from '@emotion/react';
backgroundColor: theme.canvas.palette.primary.main
// New
import { brand } from '@workday/canvas-tokens-web';
backgroundColor: cssVar(brand.primary.base)
```
Spacing Token Migration
=======================
Old spacing tokens → New system space tokens:
space.zero → system.space.zero
space.xxxs → system.space.x1
space.xxs → system.space.x2
space.xs → system.space.x3
space.s → system.space.x4
space.m → system.space.x6
space.l → system.space.x8
space.xl → system.space.x10
space.xxl → system.space.x16
space.xxxl → system.space.x20
Example migration:
```
// Old
import { space } from '@workday/canvas-kit-react/tokens';
const styles = createStyles({
padding: space.l,
margin: space.m,
});
// New
import { system } from '@workday/canvas-tokens-web';
const styles = createStyles({
padding: system.space.x8,
margin: system.space.x6,
});
```
Shape (Border Radius) Token Migration
=====================================
Old border radius → New system shape tokens:
borderRadius.zero → system.shape.zero
borderRadius.s → system.shape.half
borderRadius.m → system.shape.x1
borderRadius.l → system.shape.x2
borderRadius.circle → system.shape.round
Example:
```
// Old
borderRadius: borderRadius.m
// New
borderRadius: system.shape.x1
```
Typography Token Migration
===========================
Font Family:
type.properties.fontFamilies.default → system.fontFamily.default
type.properties.fontFamilies.monospace → system.fontFamily.mono
Font Size:
type.properties.fontSizes[10] → system.fontSize.subtext.small
type.properties.fontSizes[12] → system.fontSize.subtext.medium
type.properties.fontSizes[14] → system.fontSize.subtext.large
type.properties.fontSizes[16] → system.fontSize.body.small
type.properties.fontSizes[18] → system.fontSize.body.medium
type.properties.fontSizes[20] → system.fontSize.body.large
type.properties.fontSizes[24] → system.fontSize.heading.small
type.properties.fontSizes[28] → system.fontSize.heading.medium
type.properties.fontSizes[32] → system.fontSize.heading.large
type.properties.fontSizes[40] → system.fontSize.title.small
type.properties.fontSizes[48] → system.fontSize.title.medium
type.properties.fontSizes[56] → system.fontSize.title.large
Font Weight Mappings:
type.properties.fontWeights.regular → system.fontWeight.regular
type.properties.fontWeights.medium → system.fontWeight.medium
type.properties.fontWeights.bold → system.fontWeight.bold
Type Levels (Recommended)
Use complete type level tokens for consistency:
```
// Old
import { type } from '@workday/canvas-kit-react/tokens';
...type.levels.body.medium
// New
import { system } from '@workday/canvas-tokens-web';
...system.type.body.medium
```
Type Variants → Text Colors
Type variants are replaced with semantic text color tokens:
type.variant.error → system.color.text.critical.default
type.variant.hint → system.color.text.hint
type.variant.inverse → system.color.text.inverse
Depth (Shadow) Token Migration
===============================
Old depth tokens → New system depth tokens:
depth[1] → system.depth[1]
depth[2] → system.depth[2]
... etc
Important: Use boxShadow property (not depth)
```
// Old
const styles = createStyles({
depth: 1,
});
// New
const styles = createStyles({
boxShadow: system.depth[1],
});
```
Complete Migration Examples
===========================
Example 1: Card Component Migration
Before (Old Tokens):
```
import {
colors,
space,
borderRadius,
type,
depth
} 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):
```
import { createStyles, px2rem } from '@workday/canvas-kit-styling';
import { system } from '@workday/canvas-tokens-web';
const cardStyles = createStyles({
padding: system.space.x8,
backgroundColor: system.color.bg.default,
border: `solid ${px2rem(1)}`,
borderColor: system.color.border.container,
borderRadius: system.shape.x1,
color: system.color.text.default,
boxShadow: system.depth[1],
...system.type.body.medium,
});
const headerStyles = createStyles({
color: system.color.text.default,
marginBottom: system.space.x4,
...system.type.heading.small,
});
const errorTextStyles = createStyles({
color: system.color.text.critical.default,
...system.type.subtext.large,
});
```
Example 2: Form Input Migration
Before (Old Tokens):
```
import { colors, space, borderRadius } from '@workday/canvas-kit-react/tokens';
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):
```
import { system } from '@workday/canvas-tokens-web';
const inputStyles = createStyles({
padding: `${system.space.x3} ${system.space.x4}`,
backgroundColor: system.color.bg.default,
borderColor: system.color.border.default,
borderRadius: system.shape.half,
color: system.color.text.default,
'&:focus': {
borderColor: system.color.border.contrast,
backgroundColor: system.color.bg.default,
},
'&.error': {
borderColor: system.color.border.critical.default,
backgroundColor: system.color.bg.critical.default,
},
'&:disabled': {
backgroundColor: system.color.bg.disabled,
color: system.color.text.disabled,
}
});
```
Example 3: Button Migration with Brand Colors
Before (Old Tokens):
```
import { colors, space, borderRadius } from '@workday/canvas-kit-react/tokens';
import { theme } from '@emotion/react';
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):
```
import { system, brand } from '@workday/canvas-tokens-web';
const primaryButtonStyles = createStyles({
padding: `${system.space.x3} ${system.space.x6}`,
backgroundColor: brand.primary.base,
borderColor: brand.primary.base,
borderRadius: system.shape.x1,
color: brand.primary.accent,
'&:hover': {
backgroundColor: brand.primary.dark,
},
});
```
Best Practices
==============
1. Prefer System Tokens
Use system tokens over base tokens whenever possible for better theming support:
Good - Semantic and themeable:
backgroundColor: system.color.bg.default
Avoid - Hard-coded base value:
backgroundColor: base.neutral0
2. Use Complete Type Levels
Instead of mixing individual type properties, use complete type level tokens:
Good - Consistent type styling:
...system.type.body.medium
Avoid - Mixing individual properties:
fontSize: system.fontSize.body.medium,
fontWeight: system.fontWeight.regular,
lineHeight: '1.5'
3. Leverage Styling Utilities
Always use createStyles and cssVar for proper CSS variable handling:
Good - Proper CSS variable wrapping:
const styles = createStyles({
padding: system.space.x4,
});
Avoid - Manual CSS variable handling:
const styles = {
padding: `var(${system.space.x4})`,
};
4. Convert Pixel Values
Use px2rem for pixel-based values to maintain consistency:
import { px2rem } from '@workday/canvas-kit-styling';
const styles = createStyles({
border: `solid ${px2rem(1)}`,
borderColor: system.color.border.container,
});
Common Pitfalls & Solutions
===========================
1. 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.
2. 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.
3. Mixing Old and New Tokens
Problem: Inconsistent styling and potential conflicts.
Solution: Migrate completely to new tokens rather than mixing systems.
4. 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
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