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
Change | Short Description | Developer Impact |
---|---|---|
New Token Structure & Naming Convention | A new token structure and updated token naming convention will be rolled out | None |
New Opacity System Token | A new opacity token will be available for use with disabled states | None |
New Styling Strategy for Buttons | A new styling strategy will be rolled out to Canvas buttons in order to make buttons compatible with CSS variables while moving away from Emotion | None |
Token Rollout to Canvas Buttons | Canvas Primary, Secondary, Tertiary, and Delete buttons will be updated to use the new token set | None |
Space & Depth Rem Conversion | Space and Depth tokens will be converted from pixel to rem | Low |
Deprecation of spaceNumbers | In favor of moving to rems, spaceNumbers will be deprecated | None |
Select Compound Component Conversion | A new Select compound component will replace the current Select component in Main | Medium |
Deprecation of Select in Preview | The Select component in Preview will be deprecated | None |
Deprecation of InputIconContainer | The InputIconContainer utility will be deprecated | None |
Deprecation of Table in Main | The Table component in Main will be deprecated | None |
This guide contains an overview of the changes in Canvas Kit v10. Please reach out if you have any questions.
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
:
px Value | rem Value | space Token |
---|---|---|
0 | 0 | zero |
4px | 0.25rem | xxxs |
8px | 0.5rem | xxs |
12px | 0.75rem | xs |
16px | 1rem | s |
24px | 1.5rem | m |
32px | 2rem | l |
40px | 2.5rem | xl |
64px | 4rem | xxl |
80px | 5rem | xxxl |
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:
Equation | rem Value |
---|---|
16px/16px | 1rem |
32px/16px | 2rem |
8px/16px | 0.5rem |
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<PrimaryButtoncolors={{// other colorsfocus: {// other colorsfocusRing: focusRing(/* options */)}}}/>// v10<PrimaryButtoncolors={{// other colorsfocus: {// 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
- Canvas Tokens v1 to Canvas Tokens v2
- 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.
Feature | Variables | Styles |
---|---|---|
Solid colors | ✅ | ✅ |
Gradients | ❌ | ✅ |
Typography | ❌ | ✅ |
Space | ✅ | ❌ |
Shape | ✅ | ❌ |
Depth | ❌ | ✅ |
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.
- Open the file. If there are updates to Canvas Web v9, review and accept those updates.
- (Optional) Create a branch or duplicate file to apply the upgrade.
- Go to the Assets Panel and open Team Libraries.
- Select Canvas Tokens and Select Swap Library
- Swap to Canvas Tokens v2.
- Wait for confirmation of library swap.
- Open the Libraries Panel again and enable Canvas Tokens v2 and disable Canvas Tokens v1.
Canvas Web v10
- If there are any updates from Canvas Web v9, go ahead and make those updates.
- Go to the Assets panel and open Team Libraries.
- Select the current library used in your file, Canvas Web v9
- Choose the 'Swap Library' option.
- Select the Canvas Web v10 library for the upgrade.
- Confirm the 'Swap Library' action.
- 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.
- Click on your Team in Figma.
- Go to the Settings tab.
- Select 'Enable Libraries for all team files.'
- Turn off the old library.
- Activate the new library.
Can't Find What You Need?
Check out our FAQ section which may help you find the information you're looking for.
FAQ Section