Canvas v14 Upgrade Guide

Upgrade Overview

The table below contains a high-level overview of the updates that will be rolled out as part of the v14 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 v14 and/or switch to the new v14 Canvas Web Figma library
• Low: minor changes are required for users to adopt the change
• Medium: a moderate amount of changes are required for users to adopt the change, such as switching out UI elements
• High: a large amount of changes are required for users to adopt the change, requiring product teams to make major design or development decisions

This guide contains an overview of the changes in Canvas Kit v14. Please reach out if you have any questions.

Why You Should Upgrade

v14.0 Introduces Workday’s new brand direction which includes a new color palette and with it, some styling updates to our components.

Please consult our v14 Visual Changes page for a visual reference of what’s changed.

Note: While v14 does not require an upgrade to our v3 tokens, we strongly advise to upgrade to the latest to ensure proper branding.

Table of Contents

• LLM Assisted Migration
• Codemod
  • Instructions
• Tokens
• Caution Naming
• Theming
  • New Documentation
  • Canvas Provider
• Component Updates
  • Avatar (Preview)
  • Branding Changes
  • Buttons
  • Card
  • Count Badge
  • Expandable
  • Hyperlink and External Hyperlink
  • Loading Dots
  • Modals and Dialogs
  • Pill (Preview)
  • Search Form (Labs)
  • Status Indicator (Preview)
  • Icons
• Deprecations
  • Avatar (Main)
  • Combobox (Labs)
  • Radio (Main)
  • Search Form (Labs)
  • Segmented Control (Main)
  • Side Panel (Main)
  • Tokens
  • useIsRTL
• Removals
  • Deprecated Buttons
  • Input Provider
  • Menu (Preview)
  • readOnlyPillStencil and removeablePillStencil
  • Text Area (Labs)
  • Text Input (Labs)
• Troubleshooting
• Glossary
  • Main
  • Preview
  • Labs

LLM Assisted Migration

AI Content

We’ve provided an LLM migration mapping file (llm-canvas-kit-upgrade-guide-v14.txt) specifically designed for use with LLM-based code assistants such as Cursor. It contains a compiled LLM consumption version of this v14 Upgrade Guide. It is not intended for direct human reference or team documentation, but rather as structured input for LLMs to automate and assist with your migration process.

Important: LLMs can make mistakes. Please verify changes using this Upgrade Guide.

How to use:

• View raw file: Open the file in a new tab to see the complete migration mapping
• Download LLM File: Save the file locally to upload or paste into your LLM/code assistant
• Use with LLM: Provide the raw content to your LLM/code assistant as context for automated migration

Codemod

We’ve provided a codemod to automatically update your code to work with most of the breaking changes in v14. 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 v12 of Canvas Kit, you’ll need to run the v13 codemod before you run v14.
• 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 v14. 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 v14 [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 v14 [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.

Tokens

Canvas Kit v14 uses @workday/canvas-tokens-web v3, which introduces new color palettes and deprecates the old “fruity” color names. For example, red replaces cinnamon, blue replaces blueberry, and green replaces greenApple. We strongly recommend upgrading to @workday/canvas-tokens-web v3, as using older versions will not match the new brand guidelines or color system. Although this dependency upgrade is not required, we’ve offered migration guides and codemods separately from the v14 upgrade so teams can upgrade when they can.

For more information and changes, please view our Tokens v3 Upgrade Guide.

Note: v3 Tokens are backwards compatible with older versions of Canvas Kit.

Follow these guides to migrate:

• If you’re still using our old tokens from @workday/canvas-kit-react/tokens, migrate to @workday/canvas-tokens-web v3 using our Canvas Kit Token Migration Guide.
• Otherwise, use our v2 to v3 Migration Guide.

🤖 The v14-tokens codemod will automatically migrate your tokens, whether you’re upgrading from old tokens or from v2 to v3. Read the codemod instructions

Caution Naming

PR: #3462

To better align with the brand refresh, Alert and Warning states are being renamed to Caution for better semantics.

This change mostly affects how you pass an error state to our input components. In most cases, our input components should be used with our FormField component to ensure correct accessibility.

Before in v13

<FormField error="alert">
  <FormField.Label>First Name</FormField.Label>
  <FormField.Field>
    <FormField.Input as={TextInput} value={value} onChange={handleChange} />
    <FormField.Hint>Cannot contain numbers</FormField.Hint>
  </FormField.Field>
</FormField>

After in v14

<FormField error="caution">
  <FormField.Label>First Name</FormField.Label>
  <FormField.Field>
    <FormField.Input as={TextInput} value={value} onChange={handleChange} />
    <FormField.Hint>Cannot contain numbers</FormField.Hint>
  </FormField.Field>
</FormField>

If you’re using the error type from @workday/canvas-kit-react/common or an error type exposed from a component, the naming has also changed.

Before in v13

import {ErrorType} from '@workday/canvas-kit-react/common';
import {TextInput} from '@workday/canvas-kit-react/text-input';
import {Switch} from '@workday/canvas-kit-react/switch';
import {TextArea} from '@workday/canvas-kit-react/text-area';
 
someFunction(ErrorType.Alert);
 
<TextInput error={TextInput.ErrorType.Alert} />
<Switch error={Switch.ErrorType.Alert} />
<TextArea error={TextArea.ErrorType.Alert} />

After in v14

import {ErrorType} from '@workday/canvas-kit-react/common';
import {TextInput} from '@workday/canvas-kit-react/text-input';
import {Switch} from '@workday/canvas-kit-react/switch';
import {TextArea} from '@workday/canvas-kit-react/text-area';
 
someFunction(ErrorType.Caution);
 
<TextInput error={TextInput.ErrorType.Caution} />
<Switch error={Switch.ErrorType.Caution} />
<TextArea error={TextArea.ErrorType.Caution} />

🤖 The codemod will handle the change of ErrorType.Alert to ErrorType.Caution and error="alert" to error="caution".

Theming

New Documentation

We’ve significantly improved our theming documentation. Please consult our new Canvas Kit Theming Guide.

Canvas Provider 🚨

PRs: #3407, #3429

• CanvasThemePalette and CanvasTheme type have been updated to include a lighter property.
• CanvasProvider theme prop has been updated to include a lighter color for each palette.

Breaking Changes

Canvas Provider has been updated to remove default branding colors to ensure proper cascading of our CSS variables. Instead of generating a palette and shifting the brightness and darkness with chroma.js, we use oklch to generate the palette colors.

Prior to v14, CanvasProvider created a cascade barrier, which redefined brand CSS variables under a class and created a higher specificity. This made it difficult to override brand tokens in certain scenarios. v14 removes that barrier.

Before in v13

In v13, the useTheme hook would call createCanvasTheme which generated a palette given a main color via chroma.js.

<CanvasProvider theme={{canvas: {palette: {primary: {main: 'purple'}}}}}>
  <App />
</CanvasProvider>

After in v14

We use oklch to generate the palette colors. The color shifting will be different. If you want more control over the colors, we suggest providing the full palette object.

<CanvasProvider
  theme={{
    canvas: {
      palette: {
        primary: {
          lightest: base.blue25,
          light: base.blue200,
          main: base.blue600,
          dark: base.blue700,
          darkest: base.blue800,
          contrast: base.neutral0,
        },
      },
    },
  }}
>
  <App />
</CanvasProvider>

Or

<CanvasProvider theme={{canvas: {palette: {primary: {main: base.blue600}}}}}>
  <App />
</CanvasProvider>

Note: The way chroma.js and oklch generate colors is different. While we work on a better algorithm to determine hue, chroma and lightness and color shifting that best represents an accessible palette, you may see color discrepancies. If you want to continue using the old way of generating a color palette with chroma.js, you can use createCanvasTheme.

<CanvasProvider
  theme={{canvas: createCanvasTheme({palette: {primary: {main: cssVar(base.blue600)}}})}}
>
  <App />
</CanvasProvider>

The reason for this change is to ensure that the CSS variables properly cascade to all components. Before in v13, the CanvasProvider would add the brand tokens under a class name, creating a higher specificity.

useIsRTL

PR: #3477

The useIsRTL hook has been deprecated. Please use CSS logical properties for styling, isElementRTL for event handlers, and shouldMirrorInRTL for icons. If you need useIsRTL for any other reason, please file a issue. See the Icons section for more details on the new shouldMirrorInRTL prop.

Component Updates

Avatar (Preview)

PR: #3430

A new Avatar component has been added to the @workday/canvas-kit-preview-react package that matches our brand refresh.

API Changes from Avatar (Main)

• Avatar has a name prop. This is required to ensure a fallback if a url is not provided. The name prop also determines the initials and the alt text for the image if a url is provided.
• url is unchanged. This prop is optional and will be used to display an image Avatar.
• variant defines the color of the Avatar. It accepts the following values:
  • blue (default)
  • amber
  • teal
  • purple
• By default, the Avatar will render a div element. If you need to render a button element use the BaseAvatar component.
• size accepts the following values:
  • extraExtraLarge
  • extraLarge
  • large
  • medium (default)
  • small
  • extraSmall
  • extraExtraSmall

Avatar (Main)

import { Avatar } from '@workday/canvas-kit-react/avatar';
 
<Avatar altText="John Doe" size="extraExtraLarge" variant="light" as="div" url={yourImageUrl} />
 
// For Avatars that were buttons
<Avatar altText="John Doe" size="extraExtraLarge" variant="dark" url={yourImageUrl} />

Avatar (Preview)

import { Avatar } from '@workday/canvas-kit-preview-react/avatar';
 
<Avatar name="John Doe" size="extraExtraLarge" variant="blue" />
 
// Preferred Initials
<Avatar name="Julian Doe Smith" size="extraExtraLarge" variant="blue" preferredInitials="JS" />

Branding Changes 💅

Several components have been refactored to reflect our new brand direction. Most of these changes revolve around the use of our new brand colors. For a better guide on what has changed in our v3.0.0 tokens, please view the Tokens v3.0.0 Upgrade Guide.

The following components have been updated (see v14 Visual Changes for a visual reference of the updates):

• Breadcrumbs #3270, #3447
• Buttons #3394
• ColorPicker (Main) #3307
• ColorPicker (preview) #3307
• InformationHighlight #3443
• LoadingDots (Main) #3393
• Pagination (Preview) #3300
• Pill #3446
• SearchForm (Labs) #3303
• SegmentedControl (Main) #3278
• SegmentedControl (Preview) #3278
• ToolbarDropdownButton #3293
• ToolbarIconButton #3293

Buttons

Tertiary Button 🚨

PR: 3394

Breaking Changes

• The TertiaryButton component no longer supports the isThemable prop. To customize the appearance of TertiaryButton, use the cs prop for custom styles or the colors prop for palette-based color overrides.
• The shape of TertiaryButton has changed to have rounded corners, aligning with other buttons and our new brand direction.

Before in v13

<TertiaryButton isThemable>Themable Button</TertiaryButton>

After in v14

<TertiaryButton cs={{/* custom styles */}}>Custom Button</TertiaryButton>
// OR
<TertiaryButton colors={{/* palette colors */}}>Custom Button</TertiaryButton>

If you need to override default styles, refer to this example.

Card 🚨

PR: #3350

We’ve rebranded the Card component to align with our new brand direction and provide better visual hierarchy and more flexible styling options.

Removed Box Shadow

The default Card variant no longer includes a box shadow, creating a cleaner, flatter appearance that aligns with our new brand’s emphasis on simplicity and clarity. This is a visual breaking change that may affect your application’s visual hierarchy. If your design requires shadow you can add it through the cs prop.

Before in v13

<Card>
  <Card.Heading>Card Title</Card.Heading>
  <Card.Body>Card content with shadow</Card.Body>
</Card>

After in v14

Only do this if you need a shadow. Otherwise, adhere to the default styling.

import {system} from '@workday/canvas-tokens-web';
 
<Card cs={{boxShadow: system.depth[1]}}>
  <Card.Heading>Card Title</Card.Heading>
  <Card.Body>Card content with shadow</Card.Body>
</Card>;

New Card Variants

We’ve added two new variants to provide more styling flexibility:

• borderless: Use this variant when placing cards on colored backgrounds where it needs to blend seamlessly without borders or shadows.
• filled: Use this variant when you need a card with a grayish background to create visual separation from the page background.

The variant prop is optional. If no variant is specified, the card will use the default styling.

// Default card (no variant prop needed) with a border and no box shadow
<Card>
  <Card.Heading>Default Card</Card.Heading>
  <Card.Body>Default styling with borders, no shadow</Card.Body>
</Card>
 
// Borderless variant for colored backgrounds
<Card variant="borderless">
  <Card.Heading>Card on Colored Background</Card.Heading>
  <Card.Body>Content blends with background</Card.Body>
</Card>
 
// Filled variant with grayish background
<Card variant="filled">
  <Card.Heading>Card with grayish Background</Card.Heading>
  <Card.Body>Content with visual separation</Card.Body>
</Card>

Replaced Margins with Gap

We’ve replaced the individual margins on Card.Heading and Card.Body with gap. The card now uses display: flex with flex-direction: column by default, and the gap prop provides consistent spacing between all direct children. This provides more consistent spacing and better control over the layout. This is a visual breaking change that may affect the spacing between card elements.

Before in v13

<Card>
  <Card.Heading marginBlock="zero">Title</Card.Heading>
  <Card.Body marginBlock="zero">Card without any spacing</Card.Body>
</Card>

After in v14

<Card cs={{gap: system.space.zero}}>
  <Card.Heading>Title</Card.Heading>
  <Card.Body>Card without any spacing</Card.Body>
</Card>

Count Badge

PR: #3411

The CountBadge component has been updated to reflect our new brand direction.

Additionally, a new emphasis prop has been added, allowing you to choose between high and low emphasis for the badge.

Count Badge variants in v14

<CountBadge /> // Default count badge with high emphasis
<CountBadge variant="inverse" /> // Inverse default count badge
 
// New emphasis prop
<CountBadge emphasis="low" /> // Default count badge with low emphasis
<CountBadge variant="inverse" emphasis="low" /> // Inverse count badge with low emphasis

Expandable

PRs: #3389, #3430

The hover state of Expandable.Target has been updated to use system.color.bg.alt.soft instead of system.color.bg.alt.default to match our new brand direction.

The focus state has been updated to use system.color.border.primary.default to ensure the same focus state color across all components.

Expandable.Avatar has been updated to use the Avatar component from Preview. This change requires that you update the altText prop to name.

🤖 The codemod will handle the change of altText to name on Expandable.Avatar.

These changes are only visual and should not affect the functionality of the component.

Hyperlink and External Hyperlink

PR: #3390

Hyperlink and ExternalHyperlink now have standalone and standaloneInverse variants. This removes the underline text decoration for use outside the context of body text.

Hyperlink and ExternalHyperlink in v14

<Hyperlink variant="standalone" href="#hyperlink">Hyperlink</Hyperlink>
<ExternalHyperlink variant="standalone" href="#external-hyperlink">External Hyperlink</ExternalHyperlink>
<Hyperlink variant="standaloneInverse" href="#hyperlink">Hyperlink</Hyperlink>
<ExternalHyperlink variant="standaloneInverse" href="#external-hyperlink">External Hyperlink</ExternalHyperlink>

Note: Only use the standalone or standaloneInverse variant in cases where HyperLink and ExternalHyperlink are used outside the context of body text.

Loading Dots

PR: #3393

We’ve updated the colors to match our brand refresh. We’ve changed the default color from system.color.bg.alt.strong to system.color.bg.muted.strong.

LoadingDots now has an inverse variant. Use this variant when the Loading Dots are on a dark background or image.

After in v14

// Use inverse variant when the Loading Dots are on a dark background or image
<LoadingDots variant="inverse" />

Pill (Preview)

PRs: #3430, #3446

Pill has been updated to use the Avatar component from Preview. This change requires that you provide a value for the name prop.

🤖 The codemod will handle the change of altText to name on Pill.Avatar.

The Pill component no longer supports default as a value for the variant prop. If the variant prop is not provided, the component will use its default styling.

readOnlyPillStencil and removeablePillStencil have been removed. Please use pillStencil instead.

Before in v13

<Pill variant="default">
  <Pill.Avatar altText="John Doe" />
  <Pill.Label>John Doe</Pill.Label>
</Pill>

After in v14

<Pill>
  <Pill.Avatar name="John Doe" />
  <Pill.Label>John Doe</Pill.Label>
</Pill>

Modals and Dialogs

Previously, the usePopupStack hook created a CSS class name that was passed to our Popups. We attached those theme styles to that class name. This allowed the theme to be available in our Popups. But it also created a cascade barrier that blocked the global theme from being applied to our Popup components. Because we now use global CSS variables, we no longer need this class name to provide the global theme to Popups. But we have to remove this generated class name to allow the global theme to be applied to Popups. Instead, only the defined theme properties from the theme prop from the CanvasProvider will be applied to Popups and Modals.

If you want to have scoped theming where a part of your application needs different theming, you can still do this via the theme prop.

Note: Only the properties of the theme object that are changed will be forward to popups and modals. IE, if you change theme.palette.primary.main, only those tokens will change for popups and modals.

Scoped Theming vs Global Theming

Only use the theme prop on the CanvasProvider if you intentionally want to theme part of your application that is different from global theming.

Scoped Theming

 
<CanvasProvider theme={{canvas: {palette: {primary: {main: 'teal'}}}}}>
 {//part of your app to have different theme from the rest of your application}
</CanvasProvider>

Important: Use the theme prop on the CanvasProvider if you intentionally want to theme part of your application that is different from global theming.

Global Theming

import '@workday/canvas-tokens-web/css/base/_variables.css';
import '@workday/canvas-tokens-web/css/brand/_variables.css';
import '@workday/canvas-tokens-web/css/system/_variables.css';
 
<CanvasProvider>
  <App />
</CanvasProvider>;

Search Form (Labs) 🚨

PR: #3303

SearchThemeAttributes type has been updated. Both boxShadow and boxShadowFocus now only accept a string instead of string | string[].

Before in v13

const customTheme = {
  background: colors.cinnamon600,
  backgroundFocus: colors.frenchVanilla100,
  placeholderColor: colors.frenchVanilla100,
  placeholderColorFocus: colors.blackPepper400,
  boxShadow: ['10px 5px 5px red', '60px -16px teal'],
  boxShadowFocus: ['10px 5px 5px red', '60px -16px teal'],
} as SearchThemeAttributes;
 
<SearchForm
  searchTheme={customTheme}
  autocompleteItems={menuItems}
  onInputChange={filterMenuItems}
  onSubmit={handleSubmit}
/>;

After in v14

const customTheme = {
  background: colors.cinnamon600,
  backgroundFocus: colors.frenchVanilla100,
  placeholderColor: colors.frenchVanilla100,
  placeholderColorFocus: colors.blackPepper400,
  boxShadow: '10px 5px 5px red',
  boxShadowFocus: '10px 5px 5px red',
} as SearchThemeAttributes;
 
<SearchForm
  searchTheme={customTheme}
  autocompleteItems={menuItems}
  onInputChange={filterMenuItems}
  onSubmit={handleSubmit}
/>;

SearchTheme enum type has been updated to have string values light, dark and transparent. This should not affect the way you use the type unless you’re passing a number of 0, 1 or 2 to the searchTheme prop.

Status Indicator (Preview) 🚨

PR: #3354

Preview StatusIndicator is rounder and more vibrant with base emphasis (low).

Variant names of the preview StatusIndicator have been updated:

• blue → primary
• green → success
• orange → caution
• red → critical
• gray → neutral

The StatusIndicatorVariant type has been updated to contain the new variant names listed above. If you use the old variant values, update to use the new ones mapped above. Use StatusIndicatorProps['variant'] instead.

Before in v13

<StatusIndicator variant="blue" />
<StatusIndicator variant="green" />
<StatusIndicator variant="orange" />
<StatusIndicator variant="red" />
<StatusIndicator variant="gray" />

After in v14

<StatusIndicator variant="primary" />
<StatusIndicator variant="success" />
<StatusIndicator variant="caution" />
<StatusIndicator variant="critical" />
<StatusIndicator variant="neutral" />

Icons

PR: #3477

shouldMirrorInRTL has been added to Icon components (SVG, SystemIcon, AccentIcon, AppletIcon, SystemIconCircle, AIIngressButton, BaseButton.Icon, Button, ToolbarDropdownButton, ToolbarIconButton, ButtonLabelIcon, PrimaryButton, SecondaryButton, and TertiaryButton). This is used to mirror the icon when the content direction is rtl. This is meant to replace useIsRTL combined with the shouldMirror prop. Instead of getting the content direction from JavaScript and passing it to components, you can now pass shouldMirrorInRTL={true} to the component which will mirror the icon only when the content direction is rtl.

Before in v13

<IconComponent shouldMirror={useIsRTL()} />

After in v14

<IconComponent shouldMirrorInRTL />

You can still use shouldMirror if you intend to always mirror an icon. This is less ideal because you cannot use shouldMirror and shouldMirrorInRTL together. The icon will be mirrored regardless of content direction if both props are used.

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.

Avatar in Main

PR: #3430

We’ve deprecated the Avatar component in @workday/canvas-kit-react Main package. Please use the Avatar component in our Preview package.

Before in v13

import { Avatar } from '@workday/canvas-kit-react/avatar';
 
// For Avatars that were divs
<Avatar altText="John Doe" size="extraExtraLarge" as="div" url={yourImageUrl} />
 
// For Avatars that were buttons
<Avatar altText="John Doe" onClick={() => console.log('Avatar clicked')} />

After in v14

import {Avatar} from '@workday/canvas-kit-preview-react/avatar';
// name is used as a fallback if the image url is broken or still loading
// variant defines the color of the Avatar
<Avatar name="John Doe" size="extraExtraLarge" variant="teal" url={yourImageUrl} />;

If you need to render a button element use the BaseAvatar component.

import {BaseAvatar} from '@workday/canvas-kit-preview-react/avatar';
 
<BaseAvatar
  name="John Doe"
  size="extraExtraLarge"
  variant="teal"
  as="button"
  onClick={() => console.log('Avatar clicked')}
>
  <BaseAvatar.Name name="John Doe" />
</BaseAvatar>;

Combobox (Labs)

The Combobox component in @workday/canvas-kit-labs-react/combobox has been deprecated. Please migrate to the Combobox in @workday/canvas-kit-react.

Radio (Main)

The Radio component in @workday/canvas-kit-react/radio has been deprecated. Please migrate to the Radio in @workday/canvas-kit-preview-react for improved accessibility and API consistency.

SearchForm (Labs)

PR: #3469

The SearchForm in @workday/canvas-kit-labs-react/search-form has been deprecated. Please migrate to the Combobox in @workday/canvas-kit-react.

Segmented Control (Main)

The Segmented Control component in @workday/canvas-kit-react/segmented-control has been deprecated. Please migrate to the Segmented Control in @workday/canvas-kit-preview-react for improved features and support.

Side Panel (Main)

The Side Panel component in @workday/canvas-kit-react/side-panel has been deprecated. Please migrate to the Side Panel in @workday/canvas-kit-preview-react/side-panel for enhanced functionality.

Tokens

The legacy tokens from @workday/canvas-kit-react/tokens have been deprecated. Please use the new Canvas Tokens Web package (@workday/canvas-tokens-web) for all token usage. Follow the migration guide for a smoother upgrade.

Removals

Removals have been deleted from our codebase and may no longer be consumed. We’ve either promoted or replaced the removed component or utility.

Deprecated Buttons

PR: #3439

Long overdue, but a sign of moving forward, we’ve removed our DeprecatedButton. Our design system supported this for quite some time, but with the advancement in theming, our components API and our flexibility, it is time for us to finally remove this component. This component has served as a reminder of how far we’ve come and we’re thankful for this change.

Although unlikely, if you were using DeprecatedButton please use our flexible and themable buttons like PrimaryButton, SecondaryButton or TertiaryButton.

Input Provider

We’ve removed InputProvider from our codebase and the CanvasProvider. The intent of the provider was to check the users input and apply focus styles accordingly to our components. This was needed when we still supported IE11 to ensure we could be consistent on styling based on user input events. Since dropping support and moving to :focus-visible, we no longer need this provider. We now allow browser heuristics to determine when an element should receive visual focus styles. For more information, please view the MDN docs on :focus-visible.

If you are trying to apply focus styles to our components, we strongly advise using the :focus-visible pseudo selector.

import {createStyles} from '@workday/canvas-kit-styling'
import {PrimaryButton} from '@workday/canvas-kit-react/button'
 
const buttonStyles = createStyles({
  '&:focus-visible': {
    outline: '2px solid red'
  }
})
 
<PrimaryButton cs={buttonStyles}>
  Click Me
</PrimaryButton>

Menu (Preview)

PR: #3353

We’ve removed Menu from @workday/canvas-kit-preview-react. Please use Menu from @workday/canvas-kit-react instead.

readOnlyPillStencil and removeablePillStencil

The readOnlyPillStencil and removeablePillStencil utilities have been removed from the Pill package. Please use pillStencil instead.

Text Area (Preview)

PR: #3471

We’ve removed TextArea from @workday/canvas-kit-preview-react. Please use TextArea from @workday/canvas-kit-react instead.

Before in v13

import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
 
<TextArea orientation="vertical">
  <TextArea.Label>Leave a review</TextArea.Label>
  <TextArea.Field onChange={handleChange} value={value} />
</TextArea>;

After in v14

import {TextArea} from '@workday/canvas-kit-react/text-area';
import {FormField} from '@workday/canvas-kit-react/form-field';
 
<FormField>
  <FormField.Label>Leave a Review</FormField.Label>
  <FormField.Field>
    <FormField.Input as={TextArea} onChange={handleChange} value={value} />
  </FormField.Field>
</FormField>;

Text Input (Preview)

PR: #3471

We’ve removed TextInput from @workday/canvas-kit-preview-react. Please use TextInput from @workday/canvas-kit-react instead.

Before in v13

import {TextInput} from '@workday/canvas-kit-preview-react/text-input';
 
<TextInput orientation="vertical">
  <TextInput.Label>Email</TextInput.Label>
  <TextInput.Field onChange={handleChange} value={value} />
</TextInput>;

After in v14

import {TextArea} from '@workday/canvas-kit-react/text-area';
import {FormField} from '@workday/canvas-kit-react/form-field';
 
<FormField>
  <FormField.Label>Leave a Review</FormField.Label>
  <FormField.Field>
    <FormField.Input as={TextInput} onChange={handleChange} value={value} />
  </FormField.Field>
</FormField>;

Troubleshooting

Common Issues

• Dependency Conflicts: When upgrading to the latest major version of Canvas Kit, all related Canvas Kit packages should be updated at the same time:

  • "@workday/canvas-kit-react": "^13.5.6" → "@workday/canvas-kit-react": "^14.0.0"
  • "@workday/canvas-kit-styling": "^13.5.6" → "@workday/canvas-kit-styling": "^14.0.0"
  • "@workday/canvas-kit-preview-react": "^13.5.6" → "@workday/canvas-kit-preview-react": "^14.0.0"
  • "@workday/canvas-kit-labs-react": "^13.5.6" → "@workday/canvas-kit-labs-react": "^14.0.0"

• Token Issues: Our components rely on the @workday/canvas-tokens-web package which provides our CSS variables and ensures the correct styling of our components. Make sure to upgrade to the latest version of Canvas Tokens Web and install it correctly. For more information, view our docs.

• Color Discrepancies: If you notice visual differences after upgrading, this may be due to the change from chroma.js to oklch color generation. Consider providing explicit color values in your theme configuration.

• Build Errors: If you encounter build errors after running the codemod, ensure your linter is run as the codemod’s formatting may not match your project conventions.

Glossary

For an overview of the different packages we provide, please view our docs here.

Main

Components in the Main package are stable and ready for production use.

Preview

Components in the Preview package are mostly stable but may still receive breaking changes before being promoted to Main.

Labs

Components in the Labs package are experimental and may receive significant changes or be removed entirely.

Getting Started

This guide covers changes to Canvas Figma Libraries in v14, as well as instructions on how to update Figma files to use Canvas v14 libraries.

Deciding to Upgrade

Using versioned Figma libraries ensures that designers and developers are working with the same version of Canvas. Aligning on which version to use is essential for a smooth design-to-development handoff, ensuring that:

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

We recommend discussing with your team to determine which version of Canvas they are currently on and when they plan to upgrade to the next version. This timeline can vary from a few days to several weeks. Setting a specific upgrade date helps ensure everyone is on the same page.

Preparing for the Upgrade

Before upgrading to the latest version of Canvas, follow these best practices:

Identify Key Files for the Upgrade

Label files that need to be upgraded to Canvas Web v14 to make it easier for your team to identify which files are actively being worked on, and indicate the Canvas version in the cover thumbnail.

To minimize breaking changes, identify core screens to upgrade to the new library and limit the upgrade to only these screens. Archive older designs for future reference if necessary.

Accept Updates to the Current Version

Before upgrading to Canvas Web v14, accept any outstanding updates from the current Canvas library.

Upgrade with Figma Branches

Figma branches allow you to save a snapshot of your designs and work in a dedicated space for the upgrade. We strongly recommend creating a branch solely for the purpose of upgrading libraries - avoid making other changes in the branch to ensure a clean library swap.

Merging the branch will highlight changes made to the main file for your review. Accepting the merge will remove the branch, and apply the updates to the main file.

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

Upgrade with a Duplicate File

As an alternative to Figma branches, you may instead duplicate the file and upgrade that version without using branches. As a best practice, indicate the Canvas version number on the cover page or in the file name.

Making the Upgrade

1. Open your Figma file and accept any updates to current Canvas libraries.
2. Create a new branch (or file) for the upgrade give it a name (for example, “Upgrade to Canvas v14”)
3. Go to the active libraries tab (shortcut: ⌥ + 2).
4. Locate the current library being used, select it, and use the Library Swap feature to swap to the ‘Canvas v14’ library.
5. Merge the branch back to main, reviewing any visual differences before accepting changes back to the main file.

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

Changes to Canvas Tokens

New Additions

Color Palette and Base Library

Canvas v14 introduces a new global color palette aligned with Workday’s new brand identity. These colors replace the previous base color palette in the Canvas Tokens library.

Expanded Tonal Scale

Color palettes have been expanded to 13 steps for a more functional and comprehensive set of colors to choose from. Each step represents a defined lightness on a 0-1000 scale, where 0 is white and 1000 is black. Defining step numbers this way is to ensure colors have a consistent visual weight across color families.

For more information on how to use the scale, see color scale.

Workday Brand Integration

Colors are built by extending the core Workday brand, using them as anchor points to build accessible shades and tints from.

For a full list of brand to palette mappings, see here.

Updated Naming Convention

Base colors no longer use flavor names like Blueberry or Cinnamon. While these names can be memorable, they rely on cultural context and personal interpretation, making them less accessible to a global audience.

Instead, base colors now use common names such as blue and red, followed by a scale number. This change improves clarity and makes the color system more universally understandable for a global audience.

OKLCH Colors

In v14, we’ve switched to OKLCH as the default color space used to define and generate Canvas color palettes.

OKLCH is a uniform color space that improves the consistency of lightness and contrast across hues – a long-standing issue with traditional color spaces like RGB and HSL. OKLCH is also gamut-independent - moving towards OKLCH unlocks wider ranges of colors for the future, and enables more predictable contrast ratios between steps.

To learn more about OKLCH, see here

Predictable Contrast

The color palette ensures contrast requirements are met consistently across hues based on differences in step numbers. Colors in the same color family that are 500 apart pass WCAG AA contrast requirements for text, and colors 400 steps apart (for colors greater than 200) will pass WCAG AA contrast guidelines for non-text elements like icons and borders.

This change makes is simpler to implemnt accessible color combinations using Base colors.

Changes

Separated Base and System Token Libraries

Base colors (and tokens) have been separated from the Brand and System layer, now living in Canvas Base.

Separating these colors into their own libraries reduces the amount of colors to scroll through in the color dropdown, making it easier to find and select correct colors.

Canvas Tokens will alias to Canvas Base variables. This means that changes to Base will continue to automatically flow through to Tokens. If designing with base colors, turn on the Canvas Base library in the active libraries tab.

• Canvas Base Figma Library
• Canvas Tokens v3 Figma Library

System Color Remapping

All System and Brand colors have been updated to reference colors from the new palette. For example, bg/primary/default now references ‘palette/blue/500’ instead of palette/blueberry/500.

For a full list of mappings, see here.

Deprecations

Base colors from Canvas Tokens v2 have been deprecated in favor of the new global color palette. All system colors now reference the updated palette, ensuring consistency across the design system.

Changes to Canvas Web v14

New Additions

Color Palette Application to Components

Canvas Web components have been updated to use the new color palette through System or Brand colors. This includes:

• Breadcrumbs
• Buttons
• Card
• ColorPicker
• Loading Dots
• SearchForm
• Segmented Control
• Toolbar Dropdown Button
• Toolbar Icon Button
• Loading Sparkles
• Banner
• Status Indicator
• Expandable
• Count Badge
• Hyperlink
• Pill
• Select
• TextInput
• TextArea
• MultiSelect

Color changes will be applied automatically once users swap to the Canvas Web v14 Figma library.

New Low Emphasis Count Badge Variants

Two new Low Emphasis variants were added to Count Badge to reduce visual noise when displaying multiple counts on a page.

New Card Variations: Borderless and Filled

Two new Card variations were added:

• Borderless Cards: For use when more contrast is needed between the card and a secondary page background
• Filled Cards: For when more contrast is needed between the card and the default background color without requiring depth or borders.

New Semantic Status Indicator Variants

New semantic Status Indicator variants were added (Info, Positive, Caution, Critical) to improve accessibility for screen readers and to make intended usage more clear.

New AI Status Indicator Variant

A new AI status indicator variant was added to indicate AI-generated content, promoting transparency and helping users understand when content is created by artificial intelligence.

Changes

Updated Avatar Variants and Fallback

The Accent type has been deprecated and replaced with Color and Initials variants as fallbacks for when no image is available. This change was made to improve fallback behavior when no photo is provided by leveraging the user’s name.

Updated Inverse Count Badge Styling

Inverse Count Badge text was updated to use fg/strong instead of fg/primary to avoid confusion with interactive elements. Count Badges are not interactive, and fg/primary is meant for use on main actions on the page, such as PrimaryButtons and Links.

Updated Secondary Button Styling

SecondaryButtons have been updated to use a less prominent border color while still maintaining the recommended 3:1 contrast for interactive elements. This change was made to ensure that Secondary Buttons do not detract from main actions, like Primary Buttons.

Updated Loading Dots Styling

Loading Dots have been updated to use a darker foreground color to increase contrast against the default background color.

Updated Caution and Error States for Inputs

For Inputs, Caution and Error states now have a light amber or red background color to align with mobile input styling.

Updated Inverse Button Styling

Primary, Secondary, and Tertiary Inverse Buttons have been updated to use transparent backgrounds for interaction states to improve contrast against dynamic background colors.

Updated Tertiary Buttons and Links - No Underline on Default

Tertiary buttons and inline links have been updated to remove underlines on the default state to visually align with other Button variations. Underlines still appear on hover to provide more than one state change indicator (color and underline).

Updated Input Border Radius

All input components (TextInput, TextArea, Select) were updated to use x-half (6px) border radius instead of x-small (4px) to more clearly differentiate form elements from other elements.

Updated Toast Props to Consolidate and Boolean Props Instead

Toast variants have been consolidated using boolean props, reducing the number of variants from 12 to 3.

The ‘With Link’ and ‘With Close Icon’ variants are now controlled through boolean props rather than as separate variants, simplifying the component API and providing stronger alignment with their code counterparts.

Removed Card Depth on Default Card

The default Card component removes depth styling and applies a border/container/default border instead, aligning Canvas Cards with Platform Cards for stronger visual consistency.

Updated Status Indicators to be Rounded

Status Indicators now use fully rounded corners to increase their visual emphasis and weight on a page. This change also includes an increase in horizontal padding to account for the shape change.

Updated Breadcrumbs and Link Styling - No Underline on Default

Breadcrumb Links were updated to remove underlines by default to align with updated inline Link and Tertiary Button styling. Underlines still appear on hover to provide more than one state change indicator (color and underline).

Alert and Warning States Renamed to Caution

Alert and Warning states were renamed to “Caution” to better align with system token conventions and provide clearer semantics.

New Count Badge Emphasis Variants

New emphasis variants were added to Count Badge to support the use case of multiple counts on a page.

Deprecations

Canvas Web v11 Library Deprecation

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

Deprecated Color Status Indicators

Generic color variants (Blue, Green) are soft deprecated in favor of semantic variants (Info, Positive, Caution, Critical). Designers should use semantic variants for new designs and migrate existing designs to semantic variants when possible.

Existing design files using this library will not be impacted, but new work should use the semantic variants.

Deprecated Loading Dot Circle Variant

The Loading Dot Circle variant has been deprecated to align with the code implementation. This variant represented a custom configuration rather than a standard, out-of-the-box option.

Visual Changes

This guide contains an overview of the changes in Canvas Kit v14. If you have any issues, feel free to report them here. For a mode detailed overview of the changes in v14, please view our v14 Upgrade Guide for Developers and Designers.