Canvas v10 Upgrade Guide

Upgrade Overview

The table below contains a high-level overview of the updates that will be rolled out as part of the v10 release. The impact for 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 v9
• 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 v10. Please reach out if you have any questions.

• Codemod
• Features
  • Styling
• Removals
  • CSS Packages
  • useBanner
• Deprecations
  • Input Icon Container
  • Select (Preview)
  • Space Numbers
  • Table
• Token Updates
  • Space and Depth
• Component Updates
  • Button
  • Popups
  • Select (Main)
• Glossary
  • Main
  • Preview
  • Labs

Codemod

Unlike past major releases, v10 does not have a codemod. The changes in v10 were either deemed infeasible to codemod or provided low ROI based on consumer usage. This is subject to change; if necessary, we can release codemods as minor updates.

Codemods are here to stay and will continue to be a part of our release process. In the meantime, this Upgrade Guide should provide everything you need to update your code to be compatible with v10.

Features

Styling

PR: #2273

We've introduced a new styling package @workday/canvas-kit-styling which is a wrapper around @emotion/css.

If you're using Canvas Kit and not directly using this package, there is nothing extra to do on your end. The Canvas Kit packages are using the static compilation as part of the build process. If you want to use this package for your own styles, you don't need to do anything special to use in development; just reference our documentation on how to get started.

For more information on why this package was introduced, please reference our discussion on the future of styling for Canvas Kit.

Removals

Removals from our codebase may no longer be consumed. We've either promoted or replaced the removed component or utility.

CSS Packages

PR: #2368

We've removed the @workday/canvas-kit-css-* packages from our source code. The packages have been in maintenance mode for a while with no updates, but still riding the wave of version updates. Starting in v10, our plan is to release our CSS kit as a static build straight from our React package and under the new @workday/canvas-kit-css package. This means we're not releasing an update to the CSS package in 10.0.0, but will add our button CSS as a minor version. We're converting all our existing React packages to use this new styling strategy which will allow us to publish all CSS packages straight from the styles of our React packages, reducing the maitenance overhead required to maintain both our React kit and CSS kit.

useBanner

PR: #2318

We've removed the useBanner hook, the only function of which was to add aria-labelledby and aria-describedby references to the text inside of the Banner. This was not required for accessibility, and browsers can compute the name of the Banner from the text given inside.

Deprecations

We add the @deprecated JSDoc tag to code we plan to remove in a future major release. This signals consumers to migrate to a more stable alternative before the deprecated code is removed.

Input Icon Container

PR: #2332

We've deprecated InputIconContainer from Main because it doesn't handle bidirectionality or icons at the start of an input. Please use InputGroup instead.

Select (Preview)

PR: #2309

We've deprecated Select from Preview. Please use Select in Main instead.

Space Numbers

PR: #2345

We've deprecated spaceNumbers. Please use our rem based space tokens. If you need to calculate a value, use CSS calc() instead.

// With deprecated `spaceNumbers`
{
  paddingLeft: spaceNumbers.xl + 2; // 42px
}

// With `rem` based `space` tokens
{
  padding: `calc(${space.xl} + 2px)`; // 42px
}

For more information on how to handle this migration, please reference our discussion.

Table

PR: #2344

We've deprecated Table and TableRow and all of their exported members. Please use Table in Preview instead.

Token Updates

Space and Depth

PR: #2229

We've updated our space and depth token values from px to rem. This is based on the default browser font size which is 16px.

These updates simply mean that we have moved the values from px to rem. The values have been updated on a 1:1 basis. None of the base values have changed, only the unit.

The table below shows what each token value is, what it corresponds to, and what the new rem value is in px:

You can convert a px value to a rem value by dividing your px value by 16(if your default browser font size hasn't been updated, the value will be 16).

For example:

Why Did We Make This Change?

We wanted to move away from absolute units in tokens to relative units for better accessibility and adaptability to different viewport/screen sizes. If a user changes their default browser font size, these sizes should change along with it. px are a fixed unit and do not scale, whereas rem will allow these tokens to scale with a new default font size.

Component Updates

Button

PR: #2285

We've refactored how we style buttons to use our createStyles utility function. We don't anticipate this being a breaking change in most cases, but there may be slight changes to visual tests.

Button Icon Fill

Icons will no longer be incorrectly filled on toggle.

Button Focus Ring Update

We found that focus rings were not consistent across all buttons. We've updated the focus ring on the inverse variant of PrimaryButton to display a consistent focus ring across PrimaryButton and SecondaryButton. The changes to PrimaryButton will need to be taken note of due to small visual changes with the inverse variant.

Also, colors will no longer support the focusRing option.

import {focusRing} from '@workday/canvas-kit-react/common';

// v9
<PrimaryButton
  colors={{
    // other colors
    focus: {
      // other colors
     focusRing: focusRing(/* options */)
    }
  }}
/>

// v10
<PrimaryButton
  colors={{
    // other colors
    focus: {
      // other colors
    }
  }}
  css={{
    ':focus-visible': focusRing(/* options */)
  }}
/>;

Popups

All Popup components including Menu and Popup have increased the top and bottom spacing between the target and popup to 4px.

Select (Main)

PR: #2309

We've converted Select into a compound component which provides a flexible API and access to its internals via its subcomponents.

import {Select} from '@workday/canvas-kit-react/select';
import {FormField} from '@workday/canvas-kit-react/form-field';

// v9
<FormField label="Pizza Size">
  <Select onChange={handleChange} value={value}>
    <SelectOption label="Small" value="small" />
    <SelectOption label="Medium" value="medium" />
    <SelectOption label="Large" value="large" />
  </Select>
</FormField>

import {Select} from '@workday/canvas-kit-react/select';
import {FormField} from '@workday/canvas-kit-react/form-field';

// v10
<Select items={['Small', 'Medium', 'Large']}>
  <FormField label="Pizza Size" inputId="pizza">
    <Select.Input id="pizza" onChange={e => handleChange(e)} id="pizza" />
    <Select.Popper>
      <Select.Card maxHeight="200px">
        <Select.List>
          {item => {
            return <Select.Item>{item}</Select.Item>;
          }}
        </Select.List>
      </Select.Card>
    </Select.Popper>
  </FormField>
</Select>

Notice that Select is now outside the FormField. This is due to the update in Select and how the FormField in main applies attributes. Previously, Select was a styled native <select> input and FormField applied attributes automatically to that input. The new Select is solely a React context provider for its subcomponents. FormField needs Select.Input to be a direct child to apply attributes correctly.

Also, unlike the Select in Preview, this component does not have a border around its menu.

Glossary

Main

Our Main package of Canvas Kit tokens, components, and utilities at @workday/canvas-kit-react has 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 tokens, components, and utilities at @workday/canvas-kit-preview-react has undergone a full design and a11y review and is approved for use in product, but 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 such changes will be communicated in advance and accompanied by 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 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 tokens, components, and utilities at @workday/canvas-kit-labs-react has 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 upgrade guide will help designers with the following upgrades

1. Canvas Tokens v1 to Canvas Tokens v2
2. Canvas Web v9 to Canvas Web v10

The upgrade guide will help designers:

• Understand tokens, variables and styles.
• Decide when to upgrade.
• Prepare files for an upgrade.
• Perform the upgrade.
• Understand the changes in Canvas v10.

Intro to Variables

Canvas v10 introduces Variables to Figma libraries. Variables enable the application of tokens in design files, as as well theming capabilities within Figma.

Canvas v10 was focused on redefining and implementing a semantic token set shared between design and engineering.

Design Tokens

Design tokens are the most atomic pieces of our Design System with the primary function of storing UI information. They enable teams to build at scale and set the foundation for theming.

v10 componetns are built with a new token library using Figma variables. Variables enable theming, enforce consistency in designs, and facilitates collaboration betweeen multidisciplinary teams through a shared language.

Before v10, tokens could only be applied as a Figma Style.

Variables vs. Styles

Tokens can be represented as a Style or as a Variable in Figma.

• Styles are reusable collections of design properties that can be applied to designs.
• Variables are reusable values that can also be applied to design properties, as well as prototyping actions.

How They're the Same

• Both can serve as a source of truth for tokens
• Both may be published to team libraries
• Both may be tied to components in Figma libraries
• Both can support theming at different levels

How They're Different

• Variables hold one value, styles can hold multiple values
• Variables may reference other variables; styles cannot be referenced
• Variables are themed through modes, and styles support theming through library swapping.

Approach to Tokens

In Canvas Tokens v2, we use both Styles and Variables to represent design tokens.

To learn more about variables, view Figma's tutorial on intro to variables.

Changes in Canvas Web v10

What's New in V10

Canvas Tokens v2

Canvas Styles and variables in this library are synced to a shared token repository.

Upgrading from Canvas tokens v1 to Canvas tokens v2 will not result in breaking changes as we are not changing existing values.

New Token Structure & Naming Convention

Canvas Tokens have been restructured as a part of Canvas v10 to

• Enable scalable visual changes at the token level that flow across all Canvas components
• Increase cohesion across Canvas components by standardizing token usage with semantic tokens
• Empower product teams to build custom components using semantic tokens that can evolve with Canvas tokens

New Space & Shape Variables

Figma variables have been released as a separate token library that Canvas v10 pulls from. These Figma variables will contain the pre-set values of all Canvas space and shape tokens to help designers quickly switch between different space and shape tokens without needing to reference documentation or memorize the token values.

Variables are only visible when using the associated design property. As such, space variables are only visible within the Auto Layout window, while shape variables can only be utilized as corner radiuses in Figma.

New Color Styles & Variables

Components have been updated to point to brand styles backed by variables to match customer theming implementation.

Swapping themes under the Layers panel will now swap the brand colors to another theme, helping differentiate the parts of UI that are and are not theme-able.

Code Syntax

Variables support for CSS, SwiftUI (iOS), and Kotlin (Android).

Design tokens are platform agnostic and may be represented in different ways, depending on the programming language or design tool. Here's an example using the primary brand color.

All of these are correct for their platform (CSS, SwiftUI, and Kotlin). Prior to v10, Figma was only able to show the Style name. Now, tokens are represented in the programming language the developer is working in.

Token Rollout to Canvas Buttons

Primary, Secondary, Tertiary, and Delete Buttons have been updated to use the new system and brand-level tokens. Elements that customers can brand, such as the text color of Primary Buttons, are tied to a brand token.

This is not a breaking change for designers. Canvas buttons in the Canvas Web v10 Figma library will be linked to the new system and brand tokens automatically. Since Canvas components have always been structured to reference receipts, the new token set will also be rolled out across all Canvas components in the Canvas Web v10 Figma library.

Please note that this will temporarily create discrepancies between what is available in the code. Canvas components must be refactored in code before they can uptake the new token set.

What's Changed

Tertiary Inverse Button Styling Standardization

The inverse variant of Tertiary Buttons will be updated to align with the styling of the inverse variants of the Primary and Secondary buttons using the new token set.

By connecting the inverse variant of Tertiary Buttons to the same set of tokens used by Primary and Secondary Buttons, the background color for the hover state of the inverse Tertiary Buttons will be updated from French Vanilla 100 to Soap 300.

The new background color will be applied automatically once designers upgrade to Canvas v10 and will not result in any breaking changes. This update will also be reflected in code, but no action will be required from developers to uptake this change.

Color Styles Backed by Variables

All styles now point to a variable instead of a hard-coded value to make the transition from Styles to Variables more seamless.

Using Tokens

The Canvas Tokens v2 library is integrated into Canvas Web v10 Figma library, enabling brand theming and more seamless collaboration with engineering partners.

What's Changed

Backed Color Styles with Variables

Color styles are now backed by variables for dynamic theming and mode switching. Color variables are hidden by default for a cleaner workspace. Since color variables support all color styles, mode-switching capabilities still work as intended.

Buttons Foreground and Background Colors

Fixed a bug in Primary, Secondary, Tertiary, and Delete Buttons. Foregrounds & backgrounds now refer to the same color style to ensure theming in buttons works as intended. This update will not result in any breaking changes.

Checkbox and Radio Accent Color

Selected Checkbox and Radio accents have been updated from base French Vanilla 100 to  Primary/French Vanilla 100 to ensure a smooth transition between v9 to v10.

This update will not result in any breaking changes.

Deprecated ‘🚫Small [13px is deprecated in V.5]’ Text Styles

Previously deprecated 13px type styles have been removed in the Canvas Tokens v2 Figma library. These font sizes were deprecated in Canvas v5. They'll still be available for designers through the Canvas Tokens V1 library. However, they will not be supported in the Canvas Tokens v2 Figma library.

When designers swap over to the Canvas Tokens v2 Figma library, type styles using 13px font size will no longer be available in the Figma styles menu. However, all other types of styles will still be supported in the new Canvas Tokens v2 Figma library. Designs using the deprecated 13px text styles will persist after the library swap. Still, it is recommended for designers to switch over to using a supported text style to align with other Workday products.

Tooltip Text

Tooltip has been updated in Figma to use Subtext M - (400) Regular instead of the deprecated 13px text styles to align with what's in React.

This does not impact the lineHeight, but will decrease the overall width of the tooltip as fontSize decreases to 0.75 rem. Top and bottom padding will also increase from 0.375 to .5 rems (6 going to 8px) to maintain tooltip height.

This update will result in a visual change for designers, but the update will be applied automatically once designers upgrade to v10.

Getting Started with V10

Before Upgrading

Upgrading uses Figma's Swap Library feature and is a manual process.

Deciding to Upgrade

Coordinating the upgrade as a team is crucial. This ensures that designs align with what's technically feasible based on the version of Canvas developer partners use. We recommend discussing with your team to synchronize your upgrade schedules.

Prepare for the Upgrade

Update the Current Version

Before upgrading to Canvas Web v10, make sure to accept any changes in Canvas Web v9. While there shouldn't be any breaking changes in v10, this is a precautionary action to prevent unforeseen changes.

Identify Key Files for the Upgrade

Mark the covers of the files that should be upgraded to Canvas Web v10. This helps your team identify which files are actively being maintained and which should be archived.

Back Up Key Files

Before upgrading, consider backing up your current version through a branch.

Create a Branch of the Main File (Recommended)

Branching saves a version of your current file and creates a separate space to upgrade. Merging back to main will show the before and after, as well as any diffs.

Duplicate Key Files

Alternatively, you can duplicate essential files and upgrade those, indicating the Canvas version for clarity.

Making the Upgrade

To make the upgrade, you'll first want to make sure you resolve any updates and are using the correct tokens library.

1. Open the file. If there are updates to Canvas Web v9, review and accept those updates.
2. (Optional) Create a branch or duplicate file to apply the upgrade.

3. Go to the Assets Panel and open Team Libraries.

4. Select Canvas Tokens and Select Swap Library

5. Swap to Canvas Tokens v2.
6. Wait for confirmation of library swap.
7. Open the Libraries Panel again and enable Canvas Tokens v2 and disable Canvas Tokens v1.

Canvas Web v10

1. If there are any updates from Canvas Web v9, go ahead and make those updates.
2. Go to the Assets panel and open Team Libraries.
3. Select the current library used in your file, Canvas Web v9
4. Choose the 'Swap Library' option.
5. Select the Canvas Web v10 library for the upgrade.
6. Confirm the 'Swap Library' action.
7. Wait for Figma to confirm a successful library swap.

Any Canvas Web v9 component in your file should have been swapped to the latest Canvas Web v10 library. To test this, try changing the Brand dropdown located in the Page section on the design panel.

You should see the brand theme swap for every frame on the page.

If branching is used, Merging the branch back into the main should show you which screens were impacted by the change.

Lastly, the new library should be set to persist in your team's files. To do this, your team's admin must complete the following steps.

1. Click on your Team in Figma.
2. Go to the Settings tab.
3. Select 'Enable Libraries for all team files.'
4. Turn off the old library.
5. Activate the new library.