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 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
- 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 Color System Tokens | A new set of semantic color system tokens will be released. | None |
Updated Depth and Opacity Tokens | Depth and opacity tokens will be updated to use the new color system tokens. | None |
New Breakpoint Tokens | New breakpoint tokens will be provided to help teams apply responsive styles. | 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. | 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. | 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. | 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. | Low |
Text Components Refactor | Text components will be refactored to use the new cs prop and CSS variables. | 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. | 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. | Low |
Checkbox Refactor | Checkbox will be refactored to use the new cs prop and CSS variables with some minor visual changes. | 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. | Low |
Switch Refactor | Switch will be refactored to use the new cs prop and CSS variables with some minor visual changes. | Low |
Card Refactor | Card will be refactored to use the new cs prop and CSS variables. | None |
Select Refactor | Select will be refactored to use the new cs prop and CSS variables. | None |
Count Badge Refactor | Count Badge will be refactored to use the new cs prop and CSS variables. | None |
Component Deprecations | Text Input (Preview), Text Area (Preview), Form Field (Main), and Label Text (Main) will all be deprecated in v11. | 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/tokens
in 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
cs
prop 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.json
files 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 --devyarn canvas-kit-codemod v11 [path]yarn remove @workday/canvas-kit-codemod
Note: The codemod only works on
.js
,.jsx
,.ts
, and.tsx
files. 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.
//v10import {LabelText} from '@workday/canvas-kit-react/text';<form><LabelText>Pizza</LabelText><input type="text" /></form>;//v11import {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:
useTextInputModel
useTextInputField
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:
useStatusIndicatorModel
useStatusIndicator
statusIndicatorColors
useStatusIndicatorIcon
.
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:
Checkbox
DeleteButton
Radio
SecondaryButton
StatusIndicator
Switch
Table
TertiaryButton
TextArea
TextInput
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:
AccentIcon
AppletIcon
Card
CheckBox
Combobox
CountBadge
FormField (Preview)
DeleteButton
Graphic
LoadingDots
PrimaryButton
SecondaryButton
Radio (Preview)
Select
StatusIndicator
Svg
Switch
SystemIconCircle
SystemIcon
Table
TertiaryButton
Text
Note: These components also support our new
cs
prop for styling. Learn more about styling withcs
in our documentation.
Count Badge
PR: #2709
default
has been removed from thevariant
type 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.
hasError
prop has been renamed toerror
. This is a breaking changeerror
accepts"error" | "alert" | ""
instead of a boolean value.orientation
prop defaults tovertical
and is no longer required.FormField.Input
can be used by any of our inputs includingSelect
,TextInput
,TextArea
,RadioGroup
,Switch
andCheckbox
.FormField
does not support theuseFieldSet
prop that theFormField
in Main does. In order to achieve the same behavior, set theas
prop on theFormField
element tofieldset
and theas
prop ofFormField.Label
tolegend
.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
*ByLabelText
query.*ByRole
uses the w3c accessible name calculation specification, but*ByLabelText
uses 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 namescreen.getByRole('textbox', {name: 'Email'}); // correctly ignores the `*`v11:
screen.getByLabelText('Email');screen.getByRole('textbox', {name: 'Email'});
// v10 FormField in Previewimport {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>;// v11import {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
input
you 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
AccentIconStyles
prop has been deprecated and will be merged withAccentIconProps
in a future version.accentIconStyles
has been deprecated and will be removed in a future version as a part of implementation of stencils and new tokens. Consider usingaccentIconStencil
to get styles or class name.AccentIcon
supportssize
andcolor
css variables, along withsize
andcolor
props. Both ways are supported:
// set size or color by props<AccentIcon color={base.blueberry100} size={24} />;// set size or color by css varsimport {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
AppletIconStyles
prop has been deprecated and will be merged withAppletIconProps
in a future version.appletIconStyles
has been deprecated and will be removed in a future version as a part of implementation of stencils and new tokens. Consider usingappletIconStencil
to get styles or class name.AppletIcon
supportssize
,color200
,color300
,color400
andcolor500
css variables, along withsize
andcolor
props. Both ways are supported:
// set size or color by props<AppletIcon color="blueberry" size={240} />;// set size or color by css varsimport {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
GraphicStyles
prop has been deprecated and will be merged withGraphicProps
in a future version.graphicStyles
has been deprecated and will be removed in a future version as a part of implementation of stencils and new tokens. Consider usinggraphicStencil
to 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
SystemIconStyles
has been deprecated and will be removed in a future version as a part of implementation of stencils and new tokens. Consider usingsystemIconStencil
to get styles or class name.accentHover
is deprecated and will be removed in a future version. Please use the following when overriding styles:
'&:hover': {[systemIconStencil.vars.accent]: desiredAccentHoverColor}
backgroundHover
is deprecated and will be removed in a future version. Please use the following when overriding styles:
'&:hover': {[systemIconStencil.vars.background]: desiredBackgroundHoverColor}
fillHover
is deprecated and will be removed in a future version. Please use the following when overriding styles:
'&:hover': {[systemIconStencil.vars.fill]: desiredFillHoverColor}
fill
is deprecated and will be removed in a future version. Please usecolor
and specifyaccent
color if you wantaccent
to be different fromcolor
.
'&:hover': {[systemIconStencil.vars.fill]: desiredFillHoverColor}
systemIconStyles
has been deprecated and will be removed in a future version as a part of implementation of stencils and new tokens. Consider usingsystemIconStencil
to get styles or class name.SystemIcon
supportssize
,color
,accentColor
andbackground
css 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 varsimport {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:
rowState
prop is no longer a part of theTable
component.
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.
// v10import {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>;// v11import {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
Table
compound component, then you will need to update your import from@workday/canvas-kit-preview-react/table
to@workday/canvas-kit-react/table
. This change is not handled by the codemod.
Text
PR: #2455
Text
no longer extends theBox
component, however, it still supports Emotionstyled
and style props.- Type level components:
Title
,Heading
,BodyText
andSubtext
remain 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
createStencil
to 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. import { opacity } from "@workday/canvas-tokens-web/dist/es6/system"
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
+p
to 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.
FAQ Section