Migrating from Canvas Kit React Tokens #77

alanbsmith · 2023-12-14T23:31:01Z

alanbsmith
Dec 14, 2023
Maintainer

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

Color

Background Colors

Old Token	New Token	Role
`colors.frenchVanilla100`	`system.color.bg.default`	Main background color
`colors.blueberry200`	`system.color.bg.primary.soft`	Primary brand color (blue) selected backgrounds
`colors.blueberry400`	`system.color.bg.primary.default`	Primary brand color (blue) backgrounds
`colors.blueberry500`	`system.color.bg.primary.strong`	Primary brand color (blue) hover background
`colors.blueberry600`	`system.color.bg.primary.stronger`	Primary brand color (blue) active background
`colors.cantaloupe100`	`system.color.bg.caution.softer`	Low emphasis / Disabled warning background
`colors.cantaloupe400`	`system.color.bg.caution.default`	Default warning background
`colors.cantaloupe500`	`system.color.bg.caution.strong`	Strong / Hover warning background
`colors.cantaloupe600`	`system.color.bg.caution.stronger`	Stronger / Active warning background
`colors.cinnamon100`	`system.color.bg.critical.softer`	Low emphasis / Disabled error background"
`colors.cinnamon500`	`system.color.bg.critical.default`	Default error background
`colors.cinnamon600`	`system.color.bg.critical.strong`	Strong / Hover error background
`#80160E`	`system.color.bg.critical.stronger`	Stronger / Active error background
`colors.greenApple100`	`system.color.bg.positive.softer`	Low emphasis / Disabled success background
`colors.greenApple400`	`system.color.bg.positive.default`	Default success background
`colors.greenApple500`	`system.color.bg.positive.strong`	Strong / Hover success background
`colors.greenApple600`	`system.color.bg.positive.stronger`	Stronger / Active success background
`colors.licorice100`	`system.color.bg.muted.softer`	Disabled Muted surface background
`colors.licorice200`	`system.color.bg.muted.soft`	Low Emphasis / Muted surface background
`colors.licorice300`	`system.color.bg.muted.default`	Muted surface background
`colors.licorice500`	`system.color.bg.muted.strong`	Switch, Loading Dots
`colors.soap100`	`system.color.bg.alt.softer`	Disabled inputs and column headers
`colors.soap200`	`system.color.bg.alt.soft`	Alternative page background
`colors.soap300`	`system.color.bg.alt.default`	Secondary Surface hover, Secondary surfaces
`colors.soap400`	`system.color.bg.alt.strong`	Secondary strong hover states
`colors.soap500`	`system.color.bg.alt.stronger`	Active states
`colors.blackPepper400`	`system.color.bg.contrast.default`	Contrast backgrounds
`colors.blackPepper500`	`system.color.bg.contrast.strong`	Darker contrast background

Foreground Colors

Old Token	New Token	Role
`colors.blackPepper300`	`system.color.fg.default`	Body level foreground
`colors.blackPepper400`	`system.color.fg.strong`	Headings / Strong foreground
`colors.blackPepper500`	`system.color.fg.stronger`	Display / Strongest foreground
`colors.blueberry400`	`system.color.fg.primary.default`	Primary (blue) / Link color foreground
`colors.blueberry500`	`system.color.fg.primary.strong`	Link hover
`colors.cinnamon500`	`system.color.fg.critical.default`	Critical severity, error foregrounds
`colors.frenchVanilla100`	`system.color.fg.inverse`	Inverse foregrounds for not white backgrounds
`colors.licorice100`	`system.color.fg.disabled`	Disabled foregrounds
`colors.licorice200`	`system.color.fg.muted.soft`	Disabled Muted foreground
`colors.licorice300`	`system.color.fg.muted.default`	Muted foregrounds, like in tabs
`colors.licorice400`	`system.color.fg.muted.strong`	Muted foregrounds hover
`colors.licorice500`	`system.color.fg.muted.stronger`	Muted foregrounds active

Border Colors

Old Token	New Token	Role
`colors.blackPepper400`	`system.color.border.contrast.default`	Used to contrast on light surfaces
`colors.blackPepper500`	`system.color.border.contrast.strong`	High contrast border hover
`colors.blueberry400`	`system.color.border.primary.default`	Active input border
`colors.cantaloupe400`	`system.color.border.caution.default`	Alert input border (inner)
`colors.cantaloupe600`	`system.color.border.caution.strong`	Alert input border (outer)
`colors.cinnamon500`	`system.color.border.critical.default`	Error input border
`colors.frenchVanilla100`	`system.color.border.inverse`	Used to contrast on dark surfaces
`colors.licorice100`	`system.color.border.input.disabled`	Disabled input border
`colors.licorice200`	`system.color.border.input.default`	Default input border
`colors.licorice500`	`system.color.border.input.strong`	Input border hover
`colors.soap300`	`system.color.border.input.inverse`	Borders on inverse checkboxes and radios
`colors.soap400`	`system.color.border.divider`	Divider/separators
`colors.soap500`	`system.color.border.container`	Border used in containers (Cards, Tables)

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

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 · 2024-10-23T13:49:23Z

ahayes91
Oct 23, 2024

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

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrating from Canvas Kit React Tokens #77

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 1 comment

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Migrating from Canvas Kit React Tokens #77

Uh oh!

Uh oh!

alanbsmith Dec 14, 2023 Maintainer

Migrating from Canvas Kit React Tokens

Overview

Installation

Importing CSS Variables

Using CSS Variables

Migrating Base Tokens

Color

Migrating Brand Tokens

Color

Migrating System Tokens

Color

Background Colors

Foreground Colors

Border Colors

Border Radius (Shape)

Depth

Space

Type

Font Family

Font Size

Font Weight

Type Level

Type Variants

Replies: 1 comment

Uh oh!

ahayes91 Oct 23, 2024

alanbsmith
Dec 14, 2023
Maintainer

ahayes91
Oct 23, 2024