import {StorybookInformationHighlight} from './StorybookInformationHighlight';
# Color Token Migration
## Table of Contents
- [Base Color Mapping](#base-color-mapping)
- [Brand Color Migration](#brand-color-migration)
- [System Color Usage Guide (Recommended)](#system-color-usage-guide-recommended)
- [Other Mapping](#other-mapping)
- [Migration Examples](#migration-examples)
## Base Color Mapping
Old base colors have a new base token value. Check
[these tables](https://workday.github.io/canvas-tokens/?path=/docs/guides-upgrade-guides-v3-visual-changes-base-deprecated-palette--docs)
to see visual changes.
> **Important:** Old "fruity" color tokens are deprecated and have been mapped to new palette
> colors. Note that the v3 color scale uses `oklch`, which differs from `rgb` or `hex`, so the new
> color may not be a perfect 1:1 match with the old token. It can cause **visual breaking changes**.
>
> In some cases, there may not be a direct replacement in the new palette, and the value may remain
> a deprecated token. In these situations, you may need to manually select a new color that best
> fits your needs. You can use
> [a comparison tool](https://stackblitz.com/edit/color-comparator?file=src%2FApp.tsx) to find the
> best match.
| Old Token | New Token | CSS Variable | Surface System Color | Foreground System Color | Border System Color |
| ------------------------------ | --------------------------------- | ------------------------------------ | --------------------------------------------- | ---------------------------------------- | ---------------------------------------- |
| `colors.cinnamon100` | `base.red50` | `--cnvs-base-palette-red-50` | `system.color.brand.surface.critical.strong` | `system.color.fg.danger.default` | |
| `colors.cinnamon200` | `base.red100` | `--cnvs-base-palette-red-100` | `system.color.surface.danger.default` | | |
| `colors.cinnamon300` | `base.red300` | `--cnvs-base-palette-red-300` | | | |
| `colors.cinnamon400` | `base.red400` | `--cnvs-base-palette-red-400` | | `system.color.fg.danger.default` | |
| `colors.cinnamon500` | `base.red600` | `--cnvs-base-palette-red-600` | `system.color.brand.accent.critical` | `system.color.brand.fg.critical.default` | `system.color.border.critical.default` |
| `colors.cinnamon600` | `base.red700` | `--cnvs-base-palette-red-700` | `system.color.fg.danger.strong` | `system.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` | `system.color.brand.surface.caution.strong` | | |
| `colors.cantaloupe200` | `base.amber200` | `--cnvs-base-palette-amber-200` | `system.color.surface.warning.default` | | |
| `colors.cantaloupe300` | `base.amber300` | `--cnvs-base-palette-amber-300` | | | |
| `colors.cantaloupe400` | `base.amber400` | `--cnvs-base-palette-amber-400` | `system.color.brand.accent.caution` | | `system.color.brand.focus.caution.inner` |
| `colors.cantaloupe500` | `base.amber500` | `--cnvs-base-palette-amber-500` | `system.color.brand.accent.caution` | `system.color.fg.warning.default` | |
| `colors.cantaloupe600` | `base.amber600` | `--cnvs-base-palette-amber-600` | `system.color.brand.accent.caution` | | `system.color.brand.focus.caution.outer` |
| `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` | `system.color.brand.surface.positive.strong` | | |
| `colors.greenApple100` | `base.green100` | `--cnvs-base-palette-green-100` | `system.color.brand.surface.positive.default` | | |
| `colors.greenApple200` | `base.green200` | `--cnvs-base-palette-green-200` | | `system.color.fg.success.default` | |
| `colors.greenApple600` | `base.green600` | `--cnvs-base-palette-green-600` | `system.color.accent.success.default` | `system.color.brand.fg.positive.default` | |
| `colors.greenApple700` | `base.green700` | `--cnvs-base-palette-green-700` | `system.color.brand.accent.positive` | `system.color.brand.fg.positive.strong` | |
| `colors.greenApple800` | `base.green800` | `--cnvs-base-palette-green-800` | `system.color.brand.accent.positive` | `system.color.brand.fg.positive.strong` | |
| `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` | `system.color.brand.surface.primary.default` | | |
| `colors.blueberry300` | `base.blue400` | `--cnvs-base-palette-blue-400` | | `system.color.fg.info.default` | |
| `colors.blueberry400` | `base.blue600` | `--cnvs-base-palette-blue-600` | `system.color.brand.accent.primary` | `system.color.brand.fg.primary.default` | `system.color.border.primary.default` |
| `colors.blueberry500` | `base.blue700` | `--cnvs-base-palette-blue-700` | `system.color.brand.accent.primary` | `system.color.brand.fg.primary.strong` | |
| `colors.blueberry600` | `base.blue800` | `--cnvs-base-palette-blue-800` | `system.color.brand.accent.primary` | `system.color.brand.fg.primary.strong` | |
| `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` | `system.color.accent.muted.soft` | `system.color.fg.disabled` | `system.color.fg.disabled` |
| `colors.licorice200` | `base.slate500` | `--cnvs-base-palette-slate-500` | `system.color.accent.muted.soft` | `system.color.fg.muted.default` | `system.color.border.input.default` |
| `colors.licorice300` | `base.slate600` | `--cnvs-base-palette-slate-600` | `system.color.accent.muted.default` | `system.color.fg.muted.default` | |
| `colors.licorice400` | `base.slate700` | `--cnvs-base-palette-slate-700` | `system.color.accent.muted.default` | `system.color.fg.muted.strong ` |
| `colors.licorice500` | `base.slate800` | `--cnvs-base-palette-slate-800` | `system.color.accent.muted.default` | `system.color.fg.muted.strong ` | `system.color.border.input.hover` |
| `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` | | `system.color.fg.default` | |
| `colors.blackPepper400` | `base.neutral950` | `--cnvs-base-palette-neutral-950` | `system.color.surface.contrast.default ` | `system.color.fg.strong` | `system.color.border.contrast.default` |
| `colors.blackPepper500` | `base.neutral975` | `--cnvs-base-palette-neutral-975` | `system.color.surface.contrast.strong` | `system.color.fg.stronger` | `system.color.border.contrast.strong` |
| `colors.blackPepper600` | `base.neutral1000` | `--cnvs-base-palette-neutral-1000` | | | |
| `colors.frenchVanilla100` | `base.neutral0` | `--cnvs-base-palette-neutral-0` | `system.color.surface.default` | `system.color.fg.inverse` | `system.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` | `system.color.surface.raised` | | |
| `colors.soap200` | `base.slate50` | `--cnvs-base-palette-slate-50` | `system.color.surface.alt.default` | | |
| `colors.soap300` | `base.slate100` | `--cnvs-base-palette-slate-100` | `system.color.surface.alt.default` | `system.color.border.input.inverse` | |
| `colors.soap400` | `base.slate200` | `--cnvs-base-palette-slate-200` | `system.color.surface.alt.default` | `system.color.border.default` | |
| `colors.soap500` | `base.slate300` | `--cnvs-base-palette-slate-300` | `system.color.surface.alt.default` | `system.color.border.strong` | |
| `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 | v3 Token | v4 New Token | CSS Variable |
| ------------------------------------------ | :-------------------------: | :-----------------------: | --------------------------- |
| `theme.canvas.palette.primary.lightest` | `brand.primary.lightest` | `brand.primary25` | `--cnvs-brand-primary-25` |
| `theme.canvas.palette.primary.light` | `brand.primary.light` | `brand.primary200` | `--cnvs-brand-primary-200` |
| `theme.canvas.palette.primary.main` | `brand.primary.base` | `brand.primary600` | `--cnvs-brand-primary-600` |
| `theme.canvas.palette.primary.dark` | `brand.primary.dark` | `brand.primary700` | `--cnvs-brand-primary-700` |
| `theme.canvas.palette.primary.darkest` | `brand.primary.darkest` | `brand.primary800` | `--cnvs-brand-primary-800` |
| `theme.canvas.palette.primary.contrast` | `brand.primary.accent` | `system.color.fg.inverse` | `--cnvs-brand-fg-inverse` |
| `theme.canvas.palette.error.lightest` | `brand.error.lightest` | `brand.critical25` | `--cnvs-brand-error-25` |
| `theme.canvas.palette.error.light` | `brand.error.light` | `brand.critical200` | `--cnvs-brand-error-200` |
| `theme.canvas.palette.error.main` | `brand.error.base` | `brand.critical600` | `--cnvs-brand-error-600` |
| `theme.canvas.palette.error.dark` | `brand.error.dark` | `brand.critical700` | `--cnvs-brand-error-700` |
| `theme.canvas.palette.error.darkest` | `brand.error.darkest` | `brand.critical800` | `--cnvs-brand-error-800` |
| `theme.canvas.palette.error.contrast` | `brand.error.accent` | `system.color.fg.inverse` | `--cnvs-brand-fg-inverse` |
| `theme.canvas.palette.alert.lightest` | `brand.alert.lightest` | `brand.caution.5` | `--cnvs-brand-alert-25` |
| `theme.canvas.palette.alert.light` | `brand.alert.light` | `brand.caution200` | `--cnvs-brand-alert-200` |
| `theme.canvas.palette.alert.main` | `brand.alert.base` | `brand.caution600` | `--cnvs-brand-alert-600` |
| `theme.canvas.palette.alert.dark` | `brand.alert.dark` | `brand.caution700` | `--cnvs-brand-alert-700` |
| `theme.canvas.palette.alert.darkest` | `brand.alert.darkest` | `brand.caution800` | `--cnvs-brand-alert-800` |
| `theme.canvas.palette.alert.contrast` | `brand.alert.accent` | `system.color.fg.inverse` | `--cnvs-brand-fg-inverse` |
| `theme.canvas.palette.success.lightest` | `brand.success.lightest` | `brand.positive25` | `--cnvs-brand-success-25` |
| `theme.canvas.palette.success.light` | `brand.success.light` | `brand.positive200` | `--cnvs-brand-success-200` |
| `theme.canvas.palette.success.main` | `brand.success.base` | `brand.positive600` | `--cnvs-brand-success-600` |
| `theme.canvas.palette.success.dark` | `brand.success.dark` | `brand.positive700` | `--cnvs-brand-success-700` |
| `theme.canvas.palette.success.darkest` | `brand.success.darkest` | `brand.positive800` | `--cnvs-brand-success-800` |
| `theme.canvas.palette.success.contrast` | `brand.success.accent` | `system.color.fg.inverse` | `--cnvs-brand-fg-inverse` |
| `theme.canvas.palette.neutral.lightest` | `brand.neutral.lightest` | `brand.neutral25` | `--cnvs-brand-neutral-25` |
| `theme.canvas.palette.neutral.light` | `brand.neutral.light` | `brand.neutral200` | `--cnvs-brand-neutral-200` |
| `theme.canvas.palette.neutral.main` | `brand.neutral.base` | `brand.neutral600` | `--cnvs-brand-neutral-600` |
| `theme.canvas.palette.neutral.dark` | `brand.neutral.dark` | `brand.neutral700` | `--cnvs-brand-neutral-700` |
| `theme.canvas.palette.neutral.darkest` | `brand.neutral.darkest` | `brand.neutral800` | `--cnvs-brand-neutral-800` |
| `theme.canvas.palette.neutral.contrast` | `brand.neutral.accent` | `system.color.fg.inverse` | `--cnvs-brand-fg-inverse` |
| `theme.canvas.palette.common.focusOutline` | `brand.common.focusOutline` | `brand.common.focus` | `--cnvs-brand-common-focus` |
## 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.**
- **Surface/background (`system.color.surface.*`, `system.color.brand.surface.*`,
`system.color.accent.*`)**: For all surface and container backgrounds, including pages, cards,
banners, and input fields. Choose the appropriate variant based on the visual prominence and
interaction state (default, hover, active, disabled).
- **Foreground (`system.color.fg.*`, `system.color.brand.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.*`, `system.color.brand.focus.*`)**: For outlines, dividers, and
input borders. Select the variant that matches the required emphasis or interaction state.
### Background colors
| Use Case | System Token (v4) | Old Token / React tokens | Example Usage |
| -------------------------------------- | :-------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------: | ---------------------------------------- |
| **Background Colors** | | | |
| Main page background | `system.color.surface.default` | `colors.frenchVanilla100`
`inputColors.background`
`commonColors.background` | Page layout base background |
| Disabled elements | `system.color.brand.surface.primary.default` | `colors.blueberry200` | Disabled primary buttons |
| Brand default background | `system.color.brand.accent.primary.default` | `colors.blueberry400`
`commonColors.focusBackground`
`inputColors.selectionControlFill` | Brand banners, primary button background |
| Brand hover background | `system.color.brand.accent.primary.default` | `colors.blueberry500` | Primary button hover |
| Brand active background | `system.color.brand.accent.primary.default` | `colors.blueberry600` | Primary button active |
| Warning subtle background | `system.color.brand.surface.caution.strong` | `colors.cantaloupe100` | Soft warning banners |
| Warning default background | `system.color.brand.accent.caution.default` | `colors.cantaloupe400` | Toast notifications |
| Warning hover background | `system.color.brand.accent.caution.default` | `colors.cantaloupe500` | Warning hover states |
| Warning active background | `system.color.brand.accent.caution.default` | `colors.cantaloupe600` | Warning active states |
| Error disabled background | `system.color.brand.surface.critical.strong` | `colors.cinnamon100` | Disabled error button |
| Error default background | `system.color.brand.accent.critical` | `colors.cinnamon500` | Error message background |
| Error hover background | `system.color.surface.danger.default` | `colors.cinnamon600` | Delete button hover |
| Success surface background | `system.color.brand.surface.positive.default` | `colors.greenApple100` | Cards showing success status |
| Success default background | `system.color.brand.accent.positive.default` | `colors.greenApple400` | Disabled success buttons |
| Success hover background | `system.color.brand.accent.positive.default` | `colors.greenApple500` | Success button hover |
| Success active background | `system.color.brand.accent.positive.default` | `colors.greenApple600` | Success button active |
| Muted background (subtle) | `system.color.accent.muted.soft` | `colors.licorice100` | Light containers |
| Muted background (soft) | `system.color.accent.muted.soft` | `colors.licorice200` | Form backgrounds |
| Muted background (default) | `system.color.accent.muted.default` | `colors.licorice300` | Input fields, inactive elements |
| Muted strong background | `system.color.accent.muted.default` | `colors.licorice500` | Switch toggles, loading indicators |
| Disabled input background | `system.color.surface.raised` | `colors.soap100`
`inputColors.disabled.background` | Disabled text input fields |
| Alt page background | `system.color.surface.alt.default` | `colors.soap200` | Dashboard sections |
| Secondary surface background | `system.color.surface.alt.default` | `colors.soap300`
`commonColors.backgroundAlt` | Card hover background |
| Secondary hover background | `system.color.surface.alt.default` | `colors.soap400`
`commonColors.hoverBackground` | Hover state for modals |
| Secondary active background | `system.color.surface.alt.default` | `colors.soap500` | Clicked state for surfaces |
| Contrast background (default) | `system.color.surface.contrast.default` | `colors.blackPepper400` | Tooltip background |
| Contrast background (strong) | `system.color.surface.contrast.strong` | `colors.blackPepper500` | High-contrast text container background |
| **Foreground Colors (text and icons)** | **System Token (v4)** | **Old Token / React tokens** | **Example Usage** |
| Body foreground | `system.color.fg.default` | `colors.blackPepper300`
`typeColors.body`
`typeColors.label`
`inputColors.text`
| Paragraphs, regular content |
| Headings | `system.color.fg.strong` | `colors.blackPepper400`
`typeColors.heading` | Section and card headings |
| Display titles | `system.color.fg.stronger` | `colors.blackPepper500` | Hero titles, large headings |
| Link foreground | `system.color.brand.fg.primary.default` | `colors.blueberry400`
`iconColors.active`
`statusColors.active`
`typeColors.link`
`typeColors.selectHighlight` | Anchor links |
| Link foreground hover | `system.color.brand.fg.primary.strong` | `colors.blueberry500` | Hover state for links |
| Error foreground | `system.color.brand.fg.critical.default` | `colors.cinnamon500`
`inputColors.error.icon`
`statusColors.error` | Error messages |
| Inverse (white) foreground | `system.color.fg.inverse` | `colors.frenchVanilla100`
`typeColors.inverse`
`typeColors.selectHighlightInverse`
`iconColors.inverse` | Text on dark backgrounds |
| Disabled foreground | `system.color.fg.disabled` | `colors.licorice100`
`inputColors.disabled.text`
`inputColors.disabled.icon`
`iconColors.disabled` | Disabled buttons and form inputs |
| Muted foreground (soft) | `system.color.fg.muted.default` | `colors.licorice200`
`iconColors.standard`
`inputColors.icon`
`typeColors.hint` | Tab labels, hint text |
| Muted foreground (default) | `system.color.fg.muted.default` | `colors.licorice300`
`inputColors.placeholder` | Subtitle or secondary text |
| Muted foreground (strong) | `system.color.fg.muted.strong` | `colors.licorice400` | Hover state for muted elements |
| Muted foreground (stronger) | `system.color.fg.muted.strong` | `colors.licorice500`
`iconColors.hover`
`inputColors.iconHover` | Active muted tabs text |
| **Border Colors** | **System Token (v4)** | **Old Token / React tokens** | **Example Usage** |
| 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`
`commonColors.focusOutline`
`inputColors.focusBorder` | Active input fields |
| Warning border (inner) | `system.color.brand.focus.caution.inner` | `colors.cantaloupe400`
`inputColors.alert.border`
`statusColors.warning` | Alert field inner border |
| Warning border (outer) | `system.color.brand.focus.caution.outer` | `colors.cantaloupe600` | Alert field box shadow |
| Error border | `system.color.border.critical.default` | `colors.cinnamon500`
`inputColors.error.border`
`statusColors.error` | Form field with error |
| Inverse surface border | `system.color.border.inverse` | `colors.frenchVanilla100` | Checkbox/radio on dark background |
| Disabled input border | `system.color.border.input.default` | `colors.licorice100` | Non-editable input fields |
| Default input border | `system.color.border.input.default` | `colors.licorice200`
`inputColors.border` | Normal input field border |
| Hover input border | `system.color.border.input.hover` | `colors.licorice500`
`inputColors.disabled.border` | Input field on hover |
| Inverse input border | `system.color.border.input.inverse` | `colors.soap300` | Inverse theme inputs |
| Divider/separator border | `system.color.border.default` | `colors.soap400`
`commonColors.divider` | Table rows, content separators |
| Container border (card/table edge) | `system.color.border.strong` | `colors.soap500` | Card edge or section container border |
| **Static Colors** | **System Token (v4)** | **Old Token / React tokens** | **Example Usage** |
| 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**
```javascript
// Old
import {colors} from '@workday/canvas-kit-react/tokens';
backgroundColor: colors.frenchVanilla100;
```
```js
// New
import {base} from '@workday/canvas-tokens-web';
backgroundColor: cssVar(base.neutral0);
```
**Example 2: System Color Migration**
```javascript
// Old
import {colors} from '@workday/canvas-kit-react/tokens';
const styles = createStyles({
backgroundColor: colors.frenchVanilla100,
borderColor: colors.soap500,
color: colors.blackPepper300,
});
// New - Using v4 semantic system tokens (system.color.*)
import {system} from '@workday/canvas-tokens-web';
const styles = createStyles({
backgroundColor: system.color.surface.default,
borderColor: system.color.border.strong,
color: system.color.fg.default,
});
```
**Example 3: Brand Color Migration**
```javascript
// Old
import {theme} from '@emotion/react';
backgroundColor: theme.canvas.palette.primary.main;
```
```js
// New (v4)
import {brand} from '@workday/canvas-tokens-web';
backgroundColor: cssVar(brand.primary600);
```