Canvas v11 Upgrade Guide
Upgrade Overview
The table below contains a high-level overview of the updates that will be rolled out as part of the v11 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 v11 and/or switch to the new v11 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
| Change | Short Description | Designer Impact | Developer Impact |
|---|---|---|---|
| New Color System Tokens | A new set of semantic color system tokens will be released. | None | None |
| Updated Depth and Opacity Tokens | Depth and opacity tokens will be updated to use the new color system tokens. | None | None |
| New Breakpoint Tokens | New breakpoint tokens will be provided to help teams apply responsive styles. | None | None |
| The Return of Canvas Kit CSS | Canvas Kit CSS is making a comeback! As components are restyled in Canvas Kit React, they will be made available in Canvas Kit CSS. | None | High |
| Table (Preview) Refactor & Promotion | The Table component in Preview will be refactored to use the new cs prop and CSS variables and promoted, replacing the Table in the Main package. | None | High |
| Icon Components Refactor | The Svg, System Icon, System Icon Circle, Accent Icon, Applet Icon, and Graphic icon components will all be refactored to use the new cs prop and CSS variables. | None | Medium |
| Form Field (Preview) Refactor | Form Field (Preview) will be refactored to use the new cs prop and CSS variables, making it available for use with the current input components in Main. | None | Low |
| Text Components Refactor | Text components will be refactored to use the new cs prop and CSS variables. | None | Low |
| Status Indicator (Preview) Refactor & Model Removal | The Status Indicator component in Preview will be refactored to use the new cs prop and CSS variables with some minor visual changes. Models used in Status Indicator will also be removed. | None | Low |
| Button Token Updates | Canvas Primary, Secondary, Tertiary, and Delete buttons will be updated to use the new color system tokens. Fixes will also be applied that will result in minor visual changes. | None | Low |
| Checkbox Refactor | Checkbox will be refactored to use the new cs prop and CSS variables with some minor visual changes. | None | Low |
| Radio (Preview) Refactor | The Radio component in Preview will be refactored to use the new cs prop and CSS variables with some minor visual changes. | None | Low |
| Switch Refactor | Switch will be refactored to use the new cs prop and CSS variables with some minor visual changes. | None | Low |
| Card Refactor | Card will be refactored to use the new cs prop and CSS variables. | None | None |
| Select Refactor | Select will be refactored to use the new cs prop and CSS variables. | None | None |
| Count Badge Refactor | Count Badge will be refactored to use the new cs prop and CSS variables. | None | None |
| Component Deprecations | Text Input (Preview), Text Area (Preview), Form Field (Main), and Label Text (Main) will all be deprecated in v11. | None | None |
This guide contains an overview of the changes in Canvas Kit v11. Please reach out if you have any questions.
Why You Should Upgrade
Canvas Kit v11 is transitioning into a new way of styling. Theming and building an in sync Canvas Kit CSS has been at the top of our minds. We’ve started using our new Canvas Tokens Web package to take advantage of CSS variables and provide semantic tokens that can translate to theming components.
A note to the reader:
- While we still support our old tokens from
@workday/canvas-kit-react/tokensin v11, you must install our new tokens from@workday/canvas-tokens-web. You can find more info in our docs. - In this release, we’ve introduced a
new styling API.
This shouldn’t effect the way you currently style your components. Because we’re moving away from
Emotion, support for style props will eventually be removed, however, this API provide backwards
compatability. If you want to slowly move off of Emotion as well, you can start styling components
via the
csprop or our new styling utilities.
Table of contents
- Canvas Tokens
- Codemod
- Deprecations
- Removals
- Component Style Updates
- Component Updates
- Style Utility Updates
- Troubleshooting
- Glossary
Canvas Tokens
In v11, all the components listed in this guide have started using our new
Canvas Tokens Web.
In v10, we provided token fallbacks so that a component would not be missing a token/value if the
tokens were not defined. In v11 you must add @workday/canvas-tokens-web to ensure our components
are properly styled and the variables are defined. For more information on installing and using,
please reference our tokens
docs.
Codemod
We’ve provided a codemod to automatically update your code to work with most of the breaking changes in v11. Breaking changes handled by the codemod are marked with 🤖 in the Upgrade Guide.
A codemod is a script that makes programmatic transformations on your codebase by traversing the AST, identifying patterns, and making prescribed changes. This greatly decreases opportunities for error and reduces the number of manual updates, which allows you to focus on changes that need your attention. We highly recommend you use the codemod for these reasons.
If you’re new to running codemods or if it’s been a minute since you’ve used one, there are a few things you’ll want to keep in mind.
- Our codemods are meant to be run sequentially. For example, if you’re using v8 of Canvas Kit, you’ll need to run the v9 codemod before you run v11.
- The codemod will update your code to be compatible with the specified version, but it will not
remove outdated dependencies or upgrade dependencies to the latest version. You’ll need to upgrade
dependencies on your own.
- We recommend upgrading dependencies before running the codemod.
- Always review your
package.jsonfiles to make sure your dependency versions look correct.
- The codemod will not handle every breaking change in v11. You will likely need to make some manual changes to be compatible. Use our Upgrade Guide as a checklist.
- Codemods are not bulletproof.
- Conduct a thorough PR and QA review of all changes to ensure no regressions were introduced.
- As a safety precaution, we recommend committing the changes from the codemod as a single isolated commit (separate from other changes) so you can roll back more easily if necessary.
We’re here to help! Automatic changes to your codebase can feel scary. You can always reach out to our team. We’d be very happy to walk you through the process to set you up for success.
Instructions
The easiest way to run our codemod is to use npx in your terminal.
npx @workday/canvas-kit-codemod v11 [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 v11 [path]
yarn remove @workday/canvas-kit-codemodNote: The codemod only works on
.js,.jsx,.ts, and.tsxfiles. You’ll need to manually edit other file types (.json,.mdx,.md, etc.). You may need to run your linter after executing the codemod, as its resulting formatting (spacing, quotes, etc.) may not match your project conventions.
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.
Form Field Main
PR: #2472
We’ve deprecated FormField in Main. Please use
FormField in
Preivew instead.
Label Text
PR: #2455
We’ve deprecated LabelText in Main. Please use
FormField.Label
in Preview in context of a FormField instead.
//v10
import {LabelText} from '@workday/canvas-kit-react/text';
<form>
<LabelText>Pizza</LabelText>
<input type="text" />
</form>;
//v11
import {FormField} from '@workday/canvas-kit-preview-react/form-field';
import {TextInput} from '@workday/canvas-kit-react/text-input';
<FormField>
<FormField.Label>First Name</FormField.Label>
<FormField.Input as={TextInput} value={value} onChange={e => console.log(e)} />
</FormField>;If you still want to use a label element outside of the context of a form, you can use our Text
component instead.
Text Area Preview
PR: #2472
We’ve deprecated TextArea from Preview. Please use
FormField in
Preview with TextArea in Main instead.
Text Input Preview
PR: #2472
We’ve deprecated TextInput from Preview. Please use
FormField in
Preview with TextInput in Main instead.
The following model hooks have also been deprecated:
useTextInputModeluseTextInputField
Removals
Status Indicator (Preview) Utilities
PR: #2472
As part of the styling refactor, we’ve removed the following exports that were primarily used to style the component:
useStatusIndicatorModeluseStatusIndicatorstatusIndicatorColorsuseStatusIndicatorIcon.
There should be no developer impact.
Component Style Updates
PR: #2485
The following changes address visual discrepancies between our design spec files and code. These changes should not impact the layout or behavior of a component.
Components affected:
CheckboxDeleteButtonRadioSecondaryButtonStatusIndicatorSwitchTableTertiaryButtonTextAreaTextInput
| Component | Variant | psuedo Class | Property | v10 Value | v11 Value |
|---|---|---|---|---|---|
| Checkbox | disabled | borderColor | soap600 | licorice100 | |
| Checkbox | Inverse | disabled | borderColor | soap600 | licorice100 |
| DeleteButton | disabled | backgroundColor | error.light | error.base | |
| DeleteButton | disabled | opacity | 1 | 0.4 | |
| Radio | disabled | borderColor | soap600 | licorice100 | |
| SecondaryButton | Inverse | focus | border | soap400 | transparent |
| SecondaryButton | Inverse | focus | boxShdaow (Inner Color) | blackPepper500 | blackPepper400 |
| SecondaryButton | Inverse | focus | color | blackPepper500 | blackPepper400 |
| SecondaryButton (Icon) | Inverse | focus | fill | blackPepper500 | blackPepper400 |
| StatusIndicator (Preview) | transparent | backgroundColor | blackPepper600 | rgba(0,0,0,.84) | |
| StatusIndicator (Preview) | transparent | opacity | 0.85 | Removed | |
| Switch | Checked and Disabled | backgroundColor, opacity | blueberry200 | backgroundColor: brand.primary.base opacity: system.opacity.disabled | |
| Table (Header) | borderColor | soap400 | soap500 | ||
| TertiaryButton | hover | backgroundColor | soap200 | soap300 | |
| TertiaryButton | active | backgroundColor | soap300 | soap400 | |
| TertiaryButton | active | color | primary.dark | primary.darkest | |
| TertiaryButton | disabled | borderColor | frenchVanilla100 | transparent | |
| TertiaryButton (Icon Only) | focus | fill | blackPepper500 | blackPepper400 | |
| TertiaryButton (Icon Only) | hover | fill | blackPepper500 | blackPepper400 | |
| TextArea | disabled | borderColor | soap600 | licorice100 | |
| TextInput | disabled | borderColor | soap600 | licorice100 |
Note: If you use a visual regression tool, you’ll need to update your tests to match the new visual changes.
Component Updates
Styling API and CSS Tokens
PRs: #2666, #2471, #2542, #2570, #2442, #2472, #2685, #2615, #2699, #2546, #2570, #2620, #2583, #2567, #2455, #2709
Several components have been refactored to use our new Canvas Tokens and styling API. The React interface has not changed, but CSS variables are now used for dynamic properties.
The following components are affected:
AccentIconAppletIconCardCheckBoxComboboxCountBadgeFormField (Preview)DeleteButtonGraphicLoadingDotsPrimaryButtonSecondaryButtonRadio (Preview)SelectStatusIndicatorSvgSwitchSystemIconCircleSystemIconTableTertiaryButtonText
Note: These components also support our new
csprop for styling. Learn more about styling withcsin our documentation.
Count Badge
PR: #2709
defaulthas been removed from thevarianttype and is now the default for styles.
We also removed the default variant and consolidated those styles into the badge’s base styles.
This will not be a breaking change for most users. However, if you have a CountBadge with an
explicit default variant, you’ll see a TypeScript error. To resolve this, simply remove the
variant prop.
// Before (v10)
<CountBadge variant="default" count={10} />
// After (v11)
<CountBadge count={10} />Form Field (Preview)
FormField in Preview is a compound component and we intend to promote it in a future
version to replace the FormField in Main. Because of this, we’ve refactored how errors
are applied to FormField in Preview in order to match the API from the FormField in
Main.
-
hasErrorprop has been renamed toerror. This is a breaking change -
erroraccepts"error" | "alert" | ""instead of a boolean value. -
orientationprop defaults toverticaland is no longer required. -
FormField.Inputcan be used by any of our inputs includingSelect,TextInput,TextArea,RadioGroup,SwitchandCheckbox. -
FormFielddoes not support theuseFieldSetprop that theFormFieldin Main does. In order to achieve the same behavior, set theasprop on theFormFieldelement tofieldsetand theasprop ofFormField.Labeltolegend. -
The required asterisk is now a pseudo element. While the asterisk was never read out loud by screen readers, Testing Library required it in the
*ByLabelTextquery.*ByRoleuses the w3c accessible name calculation specification, but*ByLabelTextuses textContent. Additional information: https://github.com/testing-library/dom-testing-library/issues/929v10:
screen.getByLabelText('Email*'); // Email is a required field and asterisk is included in name screen.getByRole('textbox', {name: 'Email'}); // correctly ignores the `*`v11:
screen.getByLabelText('Email'); screen.getByRole('textbox', {name: 'Email'});
// v10 FormField in Preview
import {FormField} from '@workday/canvas-kit-preview-react/form-field';
import {TextInput} from '@workday/canvas-kit-react/text-input';
<FormField orientation="vertical" hasError={true}>
<FormField.Label>Password</FormField.Label>
<FormField.Input as={TextInput} type="password" value={value} onChange={handleChange} />
<FormField.Hint>Must Contain a number and a capital letter</FormField.Hint>
</FormField>;
// v11
import {FormField} from '@workday/canvas-kit-preview-react/form-field';
import {TextInput} from '@workday/canvas-kit-react/text-input';
<FormField error="error">
<FormField.Label>Password</FormField.Label>
<FormField.Container>
<FormField.Input as={TextInput} type="password" value={value} onChange={handleChange} />
<FormField.Hint>Must Contain a number and a capital letter</FormField.Hint>
</FormField.Container>
</FormField>;🤖 The codemod will handle the change of hasError to error for you automatically. You may need
to check your logic to make sure it sets the appropaite value to the prop.
Note: If you use your own custom
inputyou will need to handle the styling for error and alert states.
Icons
styles prop has been removed. If you still need to style an Icon component, please use the cs
prop.
Note: Passing a token name to a style prop will not be supported in a future major version. Please use our Canvas Tokens instead.
// This will no longer be supported in a future major version
<SystemIcon color="blueberry400" />;
// Use new tokens instead.
import {base} from '@workday/canvas-tokens-web';
<SystemIcon color={base.blueberry400} />;🤖 The codemod will handle the change of renaming styles to cs for you automatically.
AccentIcon
AccentIconStylesprop has been deprecated and will be merged withAccentIconPropsin a future version.accentIconStyleshas been deprecated and will be removed in a future version as a part of implementation of stencils and new tokens. Consider usingaccentIconStencilto get styles or class name.AccentIconsupportssizeandcolorcss variables, along withsizeandcolorprops. Both ways are supported:
// set size or color by props
<AccentIcon color={base.blueberry100} size={24} />;
// set size or color by css vars
import {accentIconStencil} from '@workday/canvas-kit-react/icon';
const MyComponent = StyledRadioButton('div')({
[accentIconStencil.vars.color]: base.berrySmoothie100,
[accentIconStencil.vars.size]: '2rem',
});
<MyComponent>
<AccentIcon icon={myIcon} />
</MyComponent>;AppletIcon
AppletIconStylesprop has been deprecated and will be merged withAppletIconPropsin a future version.appletIconStyleshas been deprecated and will be removed in a future version as a part of implementation of stencils and new tokens. Consider usingappletIconStencilto get styles or class name.AppletIconsupportssize,color200,color300,color400andcolor500css variables, along withsizeandcolorprops. Both ways are supported:
// set size or color by props
<AppletIcon color="blueberry" size={240} />;
// set size or color by css vars
import {appletIconStencil} from '@workday/canvas-kit-react/icon';
const MyComponent = StyledRadioButton('div')({
[appletIconStencil.vars.size]: '2rem',
[appletIconStencil.vars.color200]: base.berrySmoothie200,
[appletIconStencil.vars.color300]: base.berrySmoothie300,
[appletIconStencil.vars.color400]: base.berrySmoothie400,
[appletIconStencil.vars.color500]: base.berrySmoothie500,
});
<MyComponent>
<AppletIcon icon={myIcon} />
</MyComponent>;Graphic
GraphicStylesprop has been deprecated and will be merged withGraphicPropsin a future version.graphicStyleshas been deprecated and will be removed in a future version as a part of implementation of stencils and new tokens. Consider usinggraphicStencilto get styles or class name.
Icon
This change only impacts internal Canvas Kit code. Icon component has been removed and is no
longer used to build our icons. It has been replaced by our Svg component. Most of our icons now
extend styles from svgStencil.
SystemIcon
-
SystemIconStyleshas been deprecated and will be removed in a future version as a part of implementation of stencils and new tokens. Consider usingsystemIconStencilto get styles or class name. -
accentHoveris deprecated and will be removed in a future version. Please use the following when overriding styles:
'&:hover': {
[systemIconStencil.vars.accent]: desiredAccentHoverColor
}backgroundHoveris deprecated and will be removed in a future version. Please use the following when overriding styles:
'&:hover': {
[systemIconStencil.vars.background]: desiredBackgroundHoverColor
}fillHoveris deprecated and will be removed in a future version. Please use the following when overriding styles:
'&:hover': {
[systemIconStencil.vars.fill]: desiredFillHoverColor
}fillis deprecated and will be removed in a future version. Please usecolorand specifyaccentcolor if you wantaccentto be different fromcolor.
'&:hover': {
[systemIconStencil.vars.fill]: desiredFillHoverColor
}-
systemIconStyleshas been deprecated and will be removed in a future version as a part of implementation of stencils and new tokens. Consider usingsystemIconStencilto get styles or class name. -
SystemIconsupportssize,color,accentColorandbackgroundcss variables, along with props. Both ways are supported:
// set size or color by props
<SystemIcon color={base.blueberry100} size={24} />;
// set size or color by css vars
import {systemIconStencil} from '@workday/canvas-kit-react/icon';
const MyComponent = StyledRadioButton('div')({
[accentIconStencil.vars.size]: '2rem',
[systemIconStencil.vars.color]: base.berrySmoothie400,
[systemIconStencil.vars.background]: base.frenchVanilla100,
// on hover:
'&:hover': {
[systemIconStencil.vars.color]: base.berrySmoothie500,
[systemIconStencil.vars.background]: 'transparent',
},
});
<MyComponent>
<SystemIcon icon={myIcon} />
</MyComponent>;Status Indicator (Preview)
PR: #2620
The transparent variant now uses system.color.bg.translucent which is a background color of
black with an opacity of 0.84.
There should be no developer impact and the visual changes are safe to accept.
Switch
PR: #2583
Switch no longer uses blueberry200 which was part of our theme object
theme.palette.primary.light for the background color to indicate a Switch that is checked and
disabled. Now, it uses blueberry400 or brand.base.primary with an opacity of 0.4 for checked
and disabled.
There should be no developer impact and the visual changes are safe to accept.
Table
PR: #2600
We’ve promoted Table from Preview to Main. It replaces the Table that was
previously in Main (for reference, see
Table
in Main from v9).
Table is a
compound component
which provides a flexible API and access to its internals via its subcomponents.
Note:
rowStateprop is no longer a part of theTablecomponent.
In v10, the Table component in Main only exposed a Table and TableRow component to
build tables.
In v11, Table now exposes every subcomponent of a semantic HTML
Table. While more verbose, it
provides more flexibility for customization.
// v10
import {Table, TableRow} from '@workday/canvas-kit-react/table';
<Table>
<thead>
<TableRow header={true}>
<th>Header Text</th>
</TableRow>
</thead>
<tbody>
<TableRow>
<td>Cell Text</td>
</TableRow>
</tbody>
</Table>;
// v11
import {Table} from '@workday/canvas-kit-react/table';
<Table>
<Table.Head>
<Table.Row>
<Table.Header>Header Text</Table.Header>
</Table.Row>
</Table.Head>
<Table.Body>
<Table.Row>
<Table.Cell>Cell Text</Table.Cell>
</Table.Row>
</Table.Body>
</Table>;Please refer to the Table examples for how to implement new tables.
Note: If you were using the Preview
Tablecompound component, then you will need to update your import from@workday/canvas-kit-preview-react/tableto@workday/canvas-kit-react/table. This change is not handled by the codemod.
Text
PR: #2455
Textno longer extends theBoxcomponent, however, it still supports Emotionstyledand style props.- Type level components:
Title,Heading,BodyTextandSubtextremain unchanged.
Style Utility Updates
createStencil
PR: #2697
Stencils were updated to automatically add box-sizing: border-box to all stencils. If your stencil
did not add this style already, it may change the way width works for the component. Our intent is
to make all elements use border box layouts to make width calculations more predictable. This change
may change the way your component works if you use the width style property.
Note: This is only a breaking change if you were using
createStencilto apply margin and padding without box-sizing. For reference, view box-sizing documentation.
Troubleshooting
My Styles Seem Broken?
Our components are reliant on our new Canvas Tokens Web package. Be sure you install
@workday/canvas-tokens-web. For more information, reference our
Getting Started docs
for this package.
Did You Upgrade All Canvas Kit Related Packages?
In order for all the packages to work in harmony, you must upgrade all Canvas Kit packages to the same version that you’re using, including:
@workday/canvas-kit-react@workday/canvas-kit-preview-react@workday/canvas-kit-labs-react@workday/canvas-kit-styling@workday/canvas-kit-react-fonts@workday/canvas-kit-docs
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 contains an overview of changes designers can expect in Canvas v11 as well as step-by-step instructions for upgrading to the latest version of the Canvas Figma libraries (Canvas Web v11 and Canvas Tokens v2).
Deciding When to Upgrade
With the release of the versioned Canvas Web Figma libraries, designers now have the ability to be on the same version of Canvas as their developers. Designers should work with their developer to align on the Canvas version that should be used in design and code. Using the same Canvas version across design and code helps promote a smooth design to development handoff process by ensuring that:
- The same components are available across Figma and code
- Component styles are consistent across Figma and code
We recommend chatting with your wider team to understand what version they are currently building with, and when they plan to upgrade to the next version of Canvas. For some teams this could take a few days, for others it could be weeks. Setting an upgrade date will keep the team on the same page.
Preparing for the Upgrade
There are things that can be done before upgrading to v11 that will streamline the process and save time. Updating the covers of your files will help identify what files are planned to upgrade to v11. This has the added benefit of helping your team differentiate what you plan to maintain going forward and what you might archive within your team’s workspaces to improve findability.
Identify Key Files for the Upgrade
Mark the covers of the files that should be upgraded to Canvas Web v11. This helps your team identify which files are actively being maintained and which should be archived. To reduce the time spent addressing breaking changes it’s recommended that the duplicate or saved version of your files are consolidated to just the key screens that are frequently used to design with. These key screens can then be updated to handle breaking changes allowing you to continue to flesh out any future designs whilst cutting back on clutter. All previous designs can be archived should you need to reference these in the future.
Back Up Key Files
Before upgrading, consider backing up your current version through a branch.
Update the Current Version
Before upgrading to Canvas Web v11, make sure to accept any changes in Canvas Web v10. While there shouldn’t be any breaking changes in v11, this is a precautionary action to prevent unforeseen changes.
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
Before starting, check which version of [Canvas Tokens] your file is using.
For teams on the Canvas Tokens v1 Figma library, start here.
For teams on the Canvas Tokens v2 Figma library, start here.
Upgrade to Canvas Tokens v2
First, make sure that you are on the most recent version of Canvas Tokens.
Steps:
- Go to your design file
- Create a Figma branch labeled ‘Upgrade to v11’
- Make sure you are in the branch you just created
- Go to active libraries using the assets panel or use
cmd+shift+pto search for ‘Libraries` - Locate and click into the Canvas Tokens v1 Figma library
- Library Swap to the Canvas Tokens v2 Figma library
- Merge the branch back into the main file
- Check any visual differences in the modal
If Styles did not swap contact #ask-canvas-design for help. Otherwise, proceed to the next section.
Upgrade to Canvas Web v11
Make sure that the previous section is complete before proceeding.
Steps:
- Go to your design file
- Accept the changes from the Canvas Tokens v2 Figma library
- Create a Figma branch labeled ‘Upgrade to v11’
- Make sure you are in the branch you just created
- Go to the file’s active libraries (located in the assets panel)
- Locate and click into the Canvas Web v10 Figma library
- Library Swap to the Canvas Web v11 Figma library
- Merge the branch back into the main file
- Check for any visual differences
Changes in Canvas Tokens v2
New tokens and token updates are now available on Canvas Tokens v2. These changes will not impact existing designs, but designers will be given access to more semantic and scalable tokens.
Features
New Color System Tokens
System level color tokens are now available in the Canvas Tokens v2 Figma library, which the Canvas Web v11 library is pulling from. These tokens are semantic, which will help teams understand how they should be applied in product.
There will be three level of color system tokens available with this release:
- Base: these color tokens are meant for one-off use cases, but should be avoided when possible as they will not always reflect the Workday brand. Examples of base color tokens include Watermelon 500 (—cnvs-base-palette-watermelon-500) and Plum 300 (—cnvs-base-palette-plum-300)
- Brand: Brand tokens should only be used when tenant branding is possible / allowed. The color that brand tokens display will be dependent on the tenant configuration.
- System: System tokens should be used in cases where tenant branding is not possible / allowed. This prevents tenant configuration from altering the color used in a component. System tokens are designed to make theming (non-tenant branding) easier in the future.
Teams are advised to use System tokens over Base tokens whenever possible and to use Brand tokens with caution.

This is a net-new feature that will not impact existing designs. To access color system tokens, designers will need to accept the changes made in the Canvas Tokens v2 Figma library in their design files.
New Breakpoint Tokens
New breakpoint tokens are now available through the Canvas Tokens v2 Figma library in the form of variables. They can be applied to auto-layout frames, allowing designers to set the min and max widths of their artboards with the new breakpoint variables.

This is a net-new feature that will not impact existing designs. To access breakpoint tokens, designers will need to accept the changes made in the Canvas Tokens v2 Figma library in their design files.
Enhancements
Updated Depth and Opacity Tokens
Depth and opacity tokens have been updated to use the new color system tokens. This does not impact the color displayed for depth and opacity tokens. Depth tokens are still available for use through Canvas Tokens v2 as a Figma style. Unfortunately, opacity tokens are still not supported in Figma.
Changes in Canvas Web v11
Several components were refactored in Canvas v11 to use the new system tokens. While these system tokens will help ensure colors are applied consistently across Workday, they may result in a few minor design changes in Canvas components as they are being refactored to align to the new standard.
Features
New Grid
A new Grid style is now available, which utilizes the new breakpoint tokens. This Grid style will mimic the Grid component in code. Designers using the existing grid styles, should swap over to use the new Grid:
- Small (320px-767px) → Grid, Layer=Small
- Medium (768px-1023px) → Grid, Layer=Medium
- Large (1024px-1439px) → Grid, Layer=Large
- Extra-Large (≥1440px) → Grid, Layer=Large
The old grid styles will be soft deprecated. This means that they will still be available for use in Canvas Web v11, but may be removed in future versions.
Enhancements
New Refactored Components
The following components refactored in v11 may have minor color updates in the Canvas Web v11 Figma library:
- Status Indicator
- Buttons (Primary, Secondary, Tertiary, Delete)
- Checkbox
- Radio
- Switch
These changes will be automatically applied once users perform a library swap over to the Canvas Web v11 Figma library.
Canvas Web v8 Library Deprecation
The Canvas Web v8 Figma library will be deprecated and moved to the Archive folder. Design files using this library will not be impacted.
Can't Find What You Need?
Check out our FAQ section which may help you find the information you're looking for. For further information, contact the #ask-canvas-design or #ask-canvas-kitchannels on Slack.