Migrating from Canvas Kit React Tokens

[alanbsmith]

Migrating from Canvas Kit React Tokens

Overview

If you've been using Canvas Kit, you're probably familiar with our former tokens in @workday/canvas-kit-react/tokens. While we still support them for now, we plan to fully replace them with our new Canvas Tokens in @workday/canvas-tokens-web so we can use CSS custom properties as a single source of truth for everything using Canvas.

Installation

yarn add @workday/canvas-tokens-web

Importing CSS Variables

Before you can use our CSS variables in your components, you'll need to import them at the top-level of your application.

You can import them in a CSS file.

/* index.css */
@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";

You can also import them in a JS or TS file:

// index.ts
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";

Using CSS Variables

One common hangup for folks switching from JavaScript variables to using CSS variables is that you'll need to wrap CSS variables in var() for their property to be applied.

// old tokens
const styles = {
  padding: space.s
}

// new tokens
const styles = {
  padding: `var(${system.space.x4})`
}

If you're using our @workday/canvas-kit-styling package, you can also use cssVar instead of template literals to get the same result.

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

const styles = {
  padding: cssVar(system.space.x4),
}

Migrating Base Tokens

Color

Migrating from our old color tokens to our new base colors is pretty straightforward. If you replace colors with base, you can easily migrate to the new tokens. There are a lot of base color tokens (144!), so we'll only list one per palette below.

📝 Visit our docs to see a full table of our base color tokens.

Old Token Name	New Token Name	New Token CSS Variable
colors.cinnamon400	base.cinnamon400	--cnvs-base-palette-cinnamon-400
colors.peach400	base.peach400	--cnvs-base-palette-peach-400
colors.chiliMango400	base.chiliMango400	--cnvs-base-palette-chili-mango-400
colors.cantaloupe400	base.cantaloupe400	--cnvs-base-palette-cantaloupe-400
colors.sourLemon400	base.sourLemon400	--cnvs-base-palette-sour-lemon-400
colors.juicyPear400	base.juicyPear400	--cnvs-base-palette-juicy-pear-400
colors.kiwi400	base.kiwi400	--cnvs-base-palette-kiwi-400
colors.greenApple400	base.greenApple400	--cnvs-base-palette-green-apple-400
colors.watermelon400	base.watermelon400	--cnvs-base-palette-watermelon-400
colors.jewel400	base.jewel400	--cnvs-base-palette-jewel-400
colors.toothpaste400	base.toothpaste400	--cnvs-base-palette-toothpaste-400
colors.blueberry400	base.blueberry400	--cnvs-base-palette-blueberry-400
colors.plum400	base.plum400	--cnvs-base-palette-plum-400
colors.berrySmoothie400	base.berrySmoothie400	--cnvs-base-palette-berry-smoothie-400
colors.blackberry400	base.blackberry400	--cnvs-base-palette-blackberry-400
colors.islandPunch400	base.islandPunch400	--cnvs-base-palette-island-punch-400
colors.grapeSoda400	base.grapeSoda400	--cnvs-base-palette-grape-soda-400
colors.pomegranate400	base.pomegranate400	--cnvs-base-palette-pomegranate-400
colors.fruitPunch400	base.fruitPunch400	--cnvs-base-palette-fruit-punch-400
colors.rootBeer400	base.rootBeer400	--cnvs-base-palette-root-beer-400
colors.toastedMarshmallow400	base.toastedMarshmallow400	--cnvs-base-palette-toasted-marshmallow-400
colors.cappuccino400	base.cappuccino400	--cnvs-base-palette-cappuccino-400
colors.licorice400	base.licorice400	--cnvs-base-palette-licorice-400
colors.blackPepper400	base.blackPepper400	--cnvs-base-palette-black-pepper-400

Migrating Brand Tokens

Our old brand tokens live in the Emotion theme object, but now we can use CSS variables directly.

Color

📝 Visit our docs to see a full table of our brand color tokens

Old Token Name	New Token Name	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.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.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.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
--	brand.common.errorInner	--cnvs-brand-common-error-inner
--	brand.common.alertInner	--cnvs-brand-common-alert-inner

Migrating System Tokens

Border Radius (Shape)

Border radius tokens are now called Shape tokens to better align with design.

📝 Visit our docs to see a full table of our system shape tokens.

Old Token Name	New Token Name	New Token CSS Variable	New Token Value
borderRadius.zero	system.shape.zero	--cnvs-sys-shape-zero	0rem
borderRadius.s	system.shape.half	--cnvs-sys-shape-half	calc(0.25rem * 0.5)
borderRadius.m	system.shape.x1	--cnvs-sys-shape-x1	0.25rem
borderRadius.l	system.shape.x2	--cnvs-sys-shape-x2	calc(0.25rem * 2)
borderRadius.circle	system.shape.round	--cnvs-sys-shape-round	calc(0.25rem * 250)

Depth

📝 Visit our docs to see a full table of our system depth tokens.

Old Token Name	New Token Name	New Token CSS Variable
depth.none	--*	--
depth[1]	system.depth[1]	--cnvs-system-depth-1
depth[2]	system.depth[2]	--cnvs-system-depth-2
depth[3]	system.depth[3]	--cnvs-system-depth-3
depth[4]	system.depth[4]	--cnvs-system-depth-4
depth[5]	system.depth[5]	--cnvs-system-depth-5
depth[6]	system.depth[6]	--cnvs-system-depth-6

*We currently do not have a token equivalent for depth.none. For now, you can use boxShadow: none.

Space

📝 Visit our docs to see a full table of our system space tokens.

Old Token Name	New Token Name	New Token CSS Variable	New Token Value
space.zero	system.space.zero	--cnvs-sys-space-zero	0
space.xxxs	system.space.x1	--cnvs-sys-space-x1	calc(0.25rem * 1)
space.xxs	system.space.x2	--cnvs-sys-space-x2	calc(0.25rem * 2)
space.xs	system.space.x3	--cnvs-sys-space-x3	calc(0.25rem * 3)
space.s	system.space.x4	--cnvs-sys-space-x4	calc(0.25rem * 4)
space.m	system.space.x6	--cnvs-sys-space-x6	calc(0.25rem * 6)
space.l	system.space.x8	--cnvs-sys-space-x8	calc(0.25rem * 8)
space.xl	system.space.x10	--cnvs-sys-space-x10	calc(0.25rem * 10)
space.xxl	system.space.x16	--cnvs-sys-space-x16	calc(0.25rem * 16)
space.xxxl	system.space.x20	--cnvs-sys-space-x20	calc(0.25rem * 20)

Type

Font Family

📝 Visit our docs to see a full table of our system font family tokens.

Old Token Name	New Token Name	New Token CSS Variable	New Token Value
type.properties.fontFamilies.default	system.fontFamily.default	--cnvs-sys-font-family-default	Roboto
type.properties.fontFamilies.monospace	system.fontFamily.mono	--cnvs-sys-font-family-mono	Roboto Mono
--	system.fontFamily.global	--cnvs-sys-font-family-global	Noto Sans

Font Size

📝 Visit our docs to see a full table of our system font size tokens.

Old Token Name	New Token Name	New Token CSS Variable	New Token Value
type.properties.fontSizes[10]	system.fontSize.subtext.small	--cnvs-sys-font-size-subtext-small	0.625rem
type.properties.fontSizes[12]	system.fontSize.subtext.medium	--cnvs-sys-font-size-subtext-medium	0.75rem
type.properties.fontSizes[14]	system.fontSize.subtext.large	--cnvs-sys-font-size-subtext-large	0.875rem
type.properties.fontSizes[16]	system.fontSize.body.small	--cnvs-sys-font-size-body-small	1rem
type.properties.fontSizes[18]	system.fontSize.body.medium	--cnvs-sys-font-size-body-medium	1.125rem
type.properties.fontSizes[20]	system.fontSize.body.large	--cnvs-sys-font-size-body-large	1.25rem
type.properties.fontSizes[24]	system.fontSize.heading.small	--cnvs-sys-font-size-heading-small	1.5rem
type.properties.fontSizes[28]	system.fontSize.heading.medium	--cnvs-sys-font-size-heading-medium	1.75rem
type.properties.fontSizes[32]	system.fontSize.heading.large	--cnvs-sys-font-size-heading-large	2rem
type.properties.fontSizes[40]	system.fontSize.title.small	--cnvs-sys-font-size-title-small	2.5rem
type.properties.fontSizes[48]	system.fontSize.title.medium	--cnvs-sys-font-size-title-medium	3rem
type.properties.fontSizes[56]	system.fontSize.title.large	--cnvs-sys-font-size-title-large	3.5rem

Font Weight

📝 Visit our docs to see a full table of our system font family tokens.

Old Token Name	New Token Name	New Token CSS Variable	New Token Value
--	system.fontWeight.light	--cnvs-system-font-weight-light	300
type.properties.fontWeights.regular	system.fontWeight.regular	--cnvs-system-font-weight-regular	400
type.properties.fontWeights.medium	system.fontWeight.medium	--cnvs-system-font-weight-medium	500
type.properties.fontWeights.bold	system.fontWeight.bold	--cnvs-system-font-weight-bold	700

Type Level

📝 Visit our docs to see a full table of our system type level tokens.

Old Token Name	New Token Name
type.levels.subtext.small	system.type.subtext.small
type.levels.subtext.medium	system.type.subtext.medium
type.levels.subtext.large	system.type.subtext.large
type.levels.body.small	system.type.body.small
type.levels.body.medium	system.type.body.medium
type.levels.body.large	system.type.body.large
type.levels.heading.small	system.type.heading.small
type.levels.heading.medium	system.type.heading.medium
type.levels.heading.large	system.type.heading.large
type.levels.title.small	system.type.title.small
type.levels.title.medium	system.type.title.medium
type.levels.title.large	system.type.title.large

Type Variants

There are no longer type variant tokens. Instead, use system text colors.

| Old Token Name         | New Token Name                       |
| ---------------------- | ------------------------------------ |
| `type.variant.error`   | `system.color.text.critical.default` |
| `type.variant.hint`    | `system.color.text.hint`             |
| `type.variant.inverse` | `system.color.text.inverse`          |

[ahayes91]

Tiny update here (I use this page a lot for converting tokens) - I think system.fontWeight.regular might need to be system.fontWeight.normal?