Canvas v13 Upgrade Guide

Upgrade Overview

The table below contains a high-level overview of the updates that will be rolled out as part of the v13 release. The impact for designers and developers are defined as follows:

• None: inapplicable to the role or no actions are required for users to adopt the change; Updates will be applied automatically once users upgrade to Canvas Kit v13 and/or switch to the new v13 Canvas Web Figma library
• Low: minor changes are required for users to adopt the change
• Medium: a moderate amount of changes are required for users to adopt the change, such as switching out UI elements
• High: a large amount of changes are required for users to adopt the change, requiring product teams to make major design or development decisions

This guide contains an overview of the changes in Canvas Kit v13. Please reach out if you have any questions. For common upgrade issues, please see the Troubleshooting section at the end of this guide.

Why You Should Upgrade

We’re really excited about the updates in Canvas Kit v13! In this release, we:

• refactored components to use our Canvas tokens and styling API
• made several accessibilty improvements
• updated our brand logos
• improved our infrastructure

Refactored Components to Use Our Styling API

We’ve continued refactoring our components to use our new styling API and new Canvas tokens. This allows us to provide a more consistent styling experience across our components.

Updated Brand Logos

As part of Workday’s brand refresh, we’ve updated our Workday logos to align with our new brand design.

Improved Support for ES Modules

We’ve updated the jsx flag in our tsconfig to react-jsx to provide better support for newer technologies including Vite. As part of this change, we’ve also updated our react peer dependencies to a minimum version of 17.0.0.

Table of Contents

• Codemod
  • Instructions
• Component Updates
  • Styling API and CSS Tokens
  • Avatar
  • Expandable
  • External Hyperlink
  • Form Field and Form Field Group
  • Pill (Preview)
  • SidePanel (Preview)
  • Tabs
• Brand Refresh
  • Logo Updates
• Infrastructure
  • Supporting react-jsx
• Troubleshooting
• Contributors
• Glossary
  • Main
  • Preview
  • Labs

Codemod

We’ve provided a codemod to automatically update your code to work with most of the breaking changes in v13. Breaking changes handled by the codemod are marked with 🤖 in the Upgrade Guide.

Instructions

The easiest way to run our codemod is to use npx in your terminal.

npx @workday/canvas-kit-codemod v13 [path]

Be sure to provide specific directories that need to be updated via the [path] argument. This decreases the amount of AST the codemod needs to traverse and reduces the chances of the script having an error. For example, if your source code lives in src/, use src/ as your [path]. Or, if you have a monorepo with three packages using Canvas Kit, provide those specific packages as your [path].

Alternatively, if you’re unable to run the codemod successfully using npx, you can install the codemod package as a dev dependency, run it with yarn, and then remove the package after you’re finished.

yarn add @workday/canvas-kit-codemod --dev
yarn canvas-kit-codemod v13 [path]
yarn remove @workday/canvas-kit-codemod

Having trouble running our codemods? View our docs for more information!

Component Updates

Styling API and Canvas Tokens 💅

Several components have been refactored to use our Canvas tokens and styling API. The React interface has not changed, but Canvas Tokens are now used for dynamic properties.

Note: These components also support our cs prop for styling. Learn more about styling with cs in our documentation.

The following components have been updated:

• ActionBar #3205
• Banner #3210
• Expandable #3128
• ExternalHyperlink #3101
• LoadingSparkles #3120
• Menu #3114
• Pill #3140
• Select #3240
• SidePanel (Preview) #3123
• Skeleton #3088
• Tabs #3119
• Tooltip #3164

Avatar 🚨

PR: #3231

The following change has been made to Avatar to ensure proper accessibility.

• The altText prop no longer has a default value of "Avatar" for better internalization. This default phrase caused some to accidentally omit translations which caused translation issues.

Note: This change also impacts Pill.Avatar and Expandable.Avatar. You must provide a value to altText to ensure proper accessibility. Our examples have been updated to reflect this change.

Before in v12

// Avatar component always had a default altText of "Avatar"
<Avatar as="div" />

After in v13

// You must provide alt text to the `altText` prop. Please choose a apt description based on your `Avatar`'s usage.
<Avatar altText="User profile avatar" as="div" />

Expandable ⚡️

PR: #3217

We’ve promoted Expandable from Labs to Main.

Before in v12

import {Expandable} from '@workday/canvas-kit-labs-react/expandable';

After in v13

import {Expandable} from '@workday/canvas-kit-react/expandable';

🤖 The codemod will handle the change of imports as shown above.

External Hyperlink 🚨

PR: #3101

The following change has been made to ExternalHyperlink to ensure proper accessibility.

• The iconLabel prop no longer has a default value of "Opens link in new window". This default phrase caused some to accidentally omit translations which caused translation issues.

Note: While the prop is not required, you must provide an iconLabel for <ExternalHyperlink /> to ensure proper accessibility. Our examples have been updated to reflect this change.

Before in v12

<ExternalHyperlink href="https://workday.com">External Hyperlink</ExternalHyperlink>

After in v13

<ExternalHyperlink href="https://workday.com" iconLabel="Navigate to Workday">
  External Hyperlink
</ExternalHyperlink>

Form Field and Form Field Group 🚨

PR: #3254

The orientation prop on the FormField component no longer accepts the deprecrated horizontal value. You must update your code to use horizontalStart. Our v12 release included a codemod to update horizontal to horizontalStart, but we kept the prop backwards-compatible. In v13, we dropped horizontal as a value, and it now requires an update.

Before in v12

<FormField orientation="horizontal">
	<FormField.Label>Label</FormField.Label>
	<FormField.Field>
		<FormField.Input as={TextInput} />
	<FormField.Field>
</FormField>

After in v13

<FormField orientation="horizontalStart">
	<FormField.Label>Label</FormField.Label>
	<FormField.Field>
		<FormField.Input as={TextInput} />
	<FormField.Field>
</FormField>

Pill (Preview) 🚨

PR: #3104

A few changes have been made to Pill to ensure proper accessibility and styling.

• The border color on hover has been updated from licorice400 to system.color.border.input.strong (licorice500) to match our design specs.
• We’ve removed extra elements and now use flex box to ensure only the label receives text overflow styles when needed.
• Setting maxWidth on the parent Pill component now styles the child elements correctly. Before v13, maxWidth wasn’t calculating the width of all its elements and wasn’t a true pixel value.

Breaking Changes

• maxWidth has been removed from the usePillModel. This config was used to style subcomponents. With the refactor to use data-part and stencils, it is no longer needed on the model. You can still apply maxWidth on the parent Pill component and the child elements will be styled accordingly.
• Pill.Icon’s no longer has a default value of "add" for the aria-label. You must provide an aria-label for Pill.Icon to ensure proper accessibility. Our examples have been updated to reflect this change.
• Pill.IconButton no longer has a default aria-label="remove". You must provide an aria-label for Pill.IconButton to ensure proper accessibility. Our examples have been updated to reflect this change.
• Pill.Label is a required element when using other subcomponents such as Pill.Icon to ensure that the label truncates correctly.

Before in v12

import {Pill, usePillModel} from '@workday/canvas-kit-preview-react/pill';
 
const model = usePillModel({
  maxWidth: 200,
});
 
<Pill model={model}>
  <Pill.Icon />
  Shoes
</Pill>;

After in v13

import {Pill} from '@workday/canvas-kit-preview-react/pill';
 
<Pill maxWidth={200}>
  <Pill.Icon aria-label='Add Shoes' />
  <Pill.Label>Shoes</Pill.Label>
</Pill>
 
<Pill maxWidth={200}>
  <Pill.Label>Shirts</Pill.Label>
  <Pill.IconButton aria-label='Remove Shirts' />
</Pill>

🤖 The codemod will handle the change adding Pill.Label if Pill.Icon or Pill.IconButton is being used.

Side Panel (Preview) 🚨

PR: #3258

When we supported IE 11 we needed to use CSS Animation to support animation events. Since we dropped support for IE11, we can now use CSS Transitions to animate the width of the SidePanel when it’s expanding or collapsing. As part of this change, we also removed the onAnimationStart prop. Since moving to transitions, React doesn’t support onTransitionStart, therefore the prop is no longer needed.

Tabs 💅

PR: #3119

• The disabled icon color has been updated to use system.color.fg.disabled. This darker icon color provides better contrast.

Note: There should be no developer impact, and the visual changes are safe to accept.

Brand Refresh ⚡️

We’ve also updated our logos to align with Workday’s brand refresh.

Logo Updates

We’ve removed the outdated Dub logos in Main and promoted the new logos that were previously in our Preview package to Main as part of the brand refresh.

Before in v12

// Importing from Main common
import {dubLogoBlue} from "@workday/canvas-kit-react/common"
 
<div dangerouslySetInnerHTML={__html: dubLogoBlue} />
 
// Importing from Preview common
import {dubLogoPrimary} from "@workday/canvas-kit-preview-react/common"
 
<div dangerouslySetInnerHTML={__html: dubLogoPrimary} />

After in v13

// New logos have been promoted to Main common AND renamed
import {dubLogoPrimary} from "@workday/canvas-kit-preview-react/common"
 
<div dangerouslySetInnerHTML={__html: dubLogoPrimary} />

🤖 The codemod will handle the renaming all the imports and updating the import path.

Infrastructure

We’ve also made some updates to our dependencies and infrastructure.

Supporting react-jsx 🚨

We’ve updated the jsx flag in our tsconfig to react-jsx. As part of this change, we’ve also updated our peer dependencies for our packages to a minimum version of react@17.0.0. This change is to provide support for modern technologies like vite and ES modules.

Breaking Changes

If you’re using react@16.x.x, you’ll need to upgrade to react@17.x.x to use Canvas Kit v13.

Note: Because of this update, you may have issues with how your code is transpiles. In that case, you will likely also need to update the way jsx transpiles. To do this you’ll need to set the runtime config to automatic in your Babel config presets. This feature is enabled through the @babel/preset-react preset and handles importing functions which JSX transpiles. Make sure you have this dev dependency installed before proceeding: yarn add -D @babel/preset-react. For more information on setting an automatic runtime for React, please review Babel’s documentation.

Here’s an example Babel config. Your configuration may vary based on your application setup.

// babel.config.json
{
  "presets": [
    [
      "@babel/preset-react",
      {
        "runtime": "automatic"
      }
    ]
  ]
}

Troubleshooting

• When upgrading to the latest major version of Canvas Kit, all related Canvas Kit packages should be updated at the same time:
  • "@workday/canvas-kit-react": "^12.5.6" -> "@workday/canvas-kit-react": "^13.0.0"
  • "@workday/canvas-kit-styling": "^12.5.6" -> "@workday/canvas-kit-styling": "^13.0.0"
  • "@workday/canvas-kit-preview-react": "^12.5.6" -> "@workday/canvas-kit-preview-react": "^13.0.0"
  • "@workday/canvas-kit-labs-react": "^12.5.6" -> "@workday/canvas-kit-labs-react": "^13.0.0"
• Our components rely on the @workday/canvas-tokens-web package which provides our CSS variables and ensures the correct styling of our components. Make sure to upgrade to the latest version of Canvas Tokens Web and install it correctly. For more information, view our docs.

Contributors

This release was made possible by the following contributors:

• @williamjstanton
• @NehaAhujaa
• @JaredMaione
• @thunguyen19

Glossary

Below is a glossary of common terms we use in this upgrade guide.

Main

Our Main package of Canvas Kit (@workday/canvas-kit-react) provides components and utilities that have undergone a full design and a11y review and is approved for use in product.

Breaking changes to code in Main will only occur during major version updates and will always be communicated in advance and accompanied by migration strategies.

Preview

Our Preview package of Canvas Kit (@workday/canvas-kit-preview-react) provides components and utilities that have undergone a full design and a11y review and are approved for use in product. But it may not be up to the high code standards upheld in the Main package. Preview is analagous to code in beta.

Breaking changes are unlikely, but possible, and can be deployed to Preview at any time without triggering a major version update. Though we will communicate those changes in advance and provide migration strategies.

Generally speaking, our goal is to eventually promote code from Preview to Main. Occasionally, a component with the same name will exist in both Main and Preview (for example, see Segmented Control which is currently in Preview and Main). In these cases, Preview serves as a staging ground for an improved version of the component with a different API. The component in Main will eventually be replaced with the one in Preview.

Labs

Our Labs package of Canvas Kit (@workday/canvas-kit-labs-react) provides components and utilities that have not undergone a full design and a11y review. Labs serves as an incubator space for new and experimental code and is analagous to code in alpha.

Breaking changes can be deployed to Labs at any time without triggering a major version update and may not be subject to the same rigor in communcation and migration strategies reserved for breaking changes in Preview and Main.

Getting Started

This guide details changes to the Canvas Figma libraries in v13 as well as instructions for upgrading to Canvas v13.

Deciding to Upgrade

Versioned Figma libraries allow designers to work with the same Canvas version as developers. Aligning on the version used in both design and code is essential for a smooth design-to-development handoff, ensuring that:

• The same components are available in both Figma and code.
• Component styling, variants, and properties are consistent.

We recommend discussing with your team to determine the current version they are using and when they plan to upgrade. This timeline can vary from a few days to several weeks. Setting a specific upgrade date helps ensure everyone is aligned.

Preparing for the Upgrade

Follow these best practices before upgrading to the new version:

Identify Key Files for the Upgrade

Label files that need to be upgraded to Canvas Web v13 to help your team recognize which files are under active maintenance, as well as which version of Canvas this file is on. Limit the upgrade to core screens to minimize breaking changes. Archive older designs for future reference if necessary.

Accept Updates to the Current Version

Before upgrading to Canvas Web v13, accept any outstanding changes from Canvas Web v12.

Upgrade in a Figma Branch

Creating a branch allows you to save the current version of your file and work in a separate space for the upgrade. We recommend creating a branch dedicated towards the sole purpose of updating from an old version (main file) to a new version (the branch).

Merging the branch will integrate your changes into the main file while highlighting any differences.

For more details on Figma branches, refer to the Figma documentation.

Upgrade in a Duplicate File

Alternatively, you can duplicate your file and upgrade that version without branching. As a best practice, indicate the Canvas version number on the cover page or in the file name.

Making the Upgrade

1. Open your Figma file and ensure it’s up-to-date by accepting any previous library updates.
2. Create a new branch for the upgrade and name it (e.g., “Upgrade to v13”).
3. Go to the active libraries tab (shortcut: ⌥ + 2).
4. Locate the v12 library, select it, and use the library swap feature to swap v12 components with the v13 library.
5. Merge the branch back to main, reviewing any visual differences before finalizing.

For more on Figma’s Library Swap feature, refer to the Figma documentation.

Canvas Tokens v2

There are no changes to the Canvas Tokens v2 library.

Changes in Canvas Web v13

Features

Added Support for Menu Hierarchy

Added support for hierarchical grouping in the Menu component. Menu items may now be grouped together in sub-groups using headers to create a folder structure, with a variation to navigate to a parent folder.

Enhancements

Component Refactoring to use Brand and System Tokens

The following components have been refactored to use System and Brand Tokens: Action Bar, Loading Sparkles, Menu, Side Panel, Skeleton, Tabs, Tooltip, Pill, and Expandable Container.

These changes will be automatically applied once users swap over to the Canvas Web v13 Figma library and will not impact existing designs.

Deprecations

Canvas Web v10 Library Deprecation

The Canvas Web v10 Figma library will be deprecated and moved to the Archive folder.

Design files using this library will not be impacted.