Skip to content

docs: Update Token Migration guide to use v4 tokens #3791

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
RayRedGoose wants to merge 9 commits into
base: prerelease/major
Choose a base branch
from
+425 −580
Open

docs: Update Token Migration guide to use v4 tokens #3791

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
cd9e14a
docs: Update Token Migration guide to use v4 tokens
RayRedGoose Feb 24, 2026
7b0e496
fix: Add code block
RayRedGoose Feb 24, 2026
a01e1d0
fix: Fix brand accent tokens
RayRedGoose Feb 24, 2026
aedcc12
Update modules/docs/mdx/tokens/TokenMigrationMappingColors.mdx
RayRedGoose Feb 24, 2026
6d149b0
Update modules/docs/mdx/tokens/TokenMigrationInstall.mdx
RayRedGoose Feb 24, 2026
a548353
Update modules/docs/mdx/tokens/TokenMigrationInstall.mdx
RayRedGoose Feb 24, 2026
ecaf8c3
fix: Fix docs
RayRedGoose Feb 25, 2026
7deba7c
fix: Fix font-weight naming
RayRedGoose Feb 25, 2026
d450198
Merge branch 'prerelease/major' into ISSUE3722-token-migration-guide
mannycarrera4 Feb 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions modules/docs/mdx/tokens/TokenMigrationCodemod.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,17 @@
import {Meta} from '@storybook/blocks';

import {StorybookInformationHighlight} from './StorybookInformationHighlight';

<Meta title="Guides/Tokens Migration/Migration Codemod" />

# Canvas Kit Tokens Migration Codemod

<StorybookInformationHighlight
variant="caution"
title="v2 -> v3 Codemod"
description="This codemod automates the migration of old Canvas Kit React tokens or @workday/canvas-tokens-web v2 tokens to the new v3 token format. Note: There is currently no codemod available for migration to v4 tokens."
Copy link
Contributor

@mannycarrera4 mannycarrera4 Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you want to add this to master instead of prerelease/major? I'd assume in major we'd have a token code mod no?

/>

This codemod helps migrate Canvas Kit tokens from `@workday/canvas-kit-react/tokens` or
`@workday/canvas-tokens-web` v2 to `@workday/canvas-tokens-web` v3 format. It automatically
transforms token usage in your codebase to use the new token system.
Expand Down
65 changes: 35 additions & 30 deletions modules/docs/mdx/tokens/TokenMigrationFinal.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ semantic meaning and theming support.
#### Before (Old Tokens)

```javascript
import {colors, space, borderRadius, type, depth} from '@workday/canvas-kit-react/tokens';
import {borderRadius, colors, depth, space, type} from '@workday/canvas-kit-react/tokens';
import {createStyles} from '@workday/canvas-kit-styling';

const cardStyles = createStyles({
Expand Down Expand Up @@ -75,25 +75,25 @@ import {createStyles, px2rem} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const cardStyles = createStyles({
padding: system.space.x8,
backgroundColor: system.color.bg.default,
padding: system.padding.xxl,
backgroundColor: system.color.surface.default,
border: `solid ${px2rem(1)}`,
borderColor: system.color.border.container,
borderRadius: system.shape.x1,
color: system.color.text.default,
borderColor: system.color.border.strong,
borderRadius: system.shape.sm,
color: system.color.fg.default,
boxShadow: system.depth[1],
...system.type.body.medium,
...system.type.body.md,
});

const headerStyles = createStyles({
color: system.color.text.default,
marginBottom: system.space.x4,
...system.type.heading.small,
color: system.color.fg.default,
marginBottom: system.gap.md,
...system.type.heading.sm,
});

const errorTextStyles = createStyles({
color: system.color.text.critical.default,
...system.type.subtext.large,
color: system.color.fg.danger.default,
...system.type.subtext.lg,
});
```

Expand All @@ -102,7 +102,8 @@ const errorTextStyles = createStyles({
#### Before (Old Tokens)

```javascript
import {colors, space, borderRadius} from '@workday/canvas-kit-react/tokens';
import {borderRadius, colors, space} from '@workday/canvas-kit-react/tokens';
import {createStyles} from '@workday/canvas-kit-styling';

const inputStyles = createStyles({
padding: `${space.xs} ${space.s}`,
Expand All @@ -128,25 +129,26 @@ const inputStyles = createStyles({
#### After (New Tokens - System Approach)

```javascript
import {createStyles, px2rem} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const inputStyles = createStyles({
padding: `${system.space.x3} ${system.space.x4}`,
backgroundColor: system.color.bg.default,
padding: `${system.padding.sm} ${system.padding.md}`,
backgroundColor: system.color.surface.default,
borderColor: system.color.border.default,
borderRadius: system.shape.half,
color: system.color.text.default,
borderRadius: px2rem(2),
color: system.color.fg.default,
'&:focus': {
borderColor: system.color.border.contrast,
backgroundColor: system.color.bg.default,
borderColor: system.color.border.primary.default,
backgroundColor: system.color.surface.default,
},
'&.error': {
borderColor: system.color.border.critical.default,
backgroundColor: system.color.bg.critical.subtle,
backgroundColor: system.color.surface.critical.default,
},
'&:disabled': {
backgroundColor: system.color.bg.disabled,
color: system.color.text.disabled,
backgroundColor: system.color.surface.raised,
color: system.color.fg.disabled,
},
});
```
Expand All @@ -156,9 +158,11 @@ const inputStyles = createStyles({
#### Before (Old Tokens)

```javascript
import {colors, space, borderRadius} from '@workday/canvas-kit-react/tokens';
import {theme} from '@emotion/react';

import {borderRadius, colors, space} from '@workday/canvas-kit-react/tokens';
import {createStyles} from '@workday/canvas-kit-styling';

const primaryButtonStyles = createStyles({
padding: `${space.xs} ${space.m}`,
backgroundColor: theme.canvas.palette.primary.main,
Expand All @@ -174,16 +178,17 @@ const primaryButtonStyles = createStyles({
#### After (New Tokens - Brand + System)

```javascript
import {system, brand} from '@workday/canvas-tokens-web';
import {createStyles} from '@workday/canvas-kit-styling';
import {brand, system} from '@workday/canvas-tokens-web';

const primaryButtonStyles = createStyles({
padding: `${system.space.x3} ${system.space.x6}`,
backgroundColor: brand.primary.base,
borderColor: brand.primary.base,
borderRadius: system.shape.x1,
color: brand.primary.accent,
padding: `${system.padding.sm} ${system.padding.xl}`,
backgroundColor: brand.primary600,
borderColor: brand.common.focus,
borderRadius: system.shape.sm,
color: system.color.fg.inverse,
'&:hover': {
backgroundColor: brand.primary.dark,
backgroundColor: brand.primary800,
},
});
```
Expand Down
30 changes: 16 additions & 14 deletions modules/docs/mdx/tokens/TokenMigrationInstall.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import {Meta} from '@storybook/blocks';

import {StorybookInformationHighlight} from './StorybookInformationHighlight';

<Meta title="Guides/Tokens Migration/Installation & Setup" />
Expand All @@ -12,10 +13,10 @@ application.

<StorybookInformationHighlight
emphasis="high"
title="Canvas Tokens v3"
description="Check out the new v3 tokens package to explore the updated token structure and see how the new CSS variable tokens look in practice. Learn more about how tokens are organized, how to use them in your application, and the benefits of migrating to the new system."
link="https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs"
linkText="View the Docs"
title="Canvas Tokens v4"
description="Check out the new v4 tokens package to explore the updated token structure and see how the new CSS variable tokens look in practice. Learn more about how tokens are organized, how to use them in your application, and the benefits of migrating to the new system."
link="https://workday.github.io/canvas-tokens/?path=/docs/guides-upgrade-guides-v4-overview--docs"
linkText="View v4 Upgrade Guide"
isExternal
/>

Expand Down Expand Up @@ -47,8 +48,8 @@ Import the variables at the top level of your application:

```javascript
import '@workday/canvas-tokens-web/css/base/_variables.css';
import '@workday/canvas-tokens-web/css/system/_variables.css';
import '@workday/canvas-tokens-web/css/brand/_variables.css';
import '@workday/canvas-tokens-web/css/system/_variables.css';
```

## Updating Your Styling Approach
Expand All @@ -71,7 +72,8 @@ If you're not already using `createStyles`, migrate from style props to the styl
```javascript
// as style props (old)
import {space, colors} from '@workday/canvas-kit-react/tokens';
<Component padding={space.s} color={colors.blackPeppers400}>

<Component padding={space.s} color={colors.blackPepper400}>
```

**Within Canvas styling functions**
Expand All @@ -85,7 +87,7 @@ import {system} from '@workday/canvas-tokens-web';

//
const styles = createStyles({
padding: system.space.x4, // not required in most cases
padding: system.padding.md, // not required in most cases
color: cssVar(system.color.fg.default, '#000') // used to provide fallback
})

Expand All @@ -103,7 +105,7 @@ import {cssVar} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

<Component style={{
padding: cssVar(system.space.x4),
padding: cssVar(system.padding.md),
color: cssVar(system.color.fg.default)
}}>
```
Expand All @@ -122,11 +124,11 @@ import {calc} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const styles = {
// returns 'calc(var(--cnvs-sys-space-x1) + 0.125rem)'
padding: calc.add(system.space.x1, '0.125rem'),
// returns 'calc(var(--cnvs-sys-space-x1) - 0.125rem)'
margin: calc.subtract(system.space.x1, '0.125rem'),
// returns 'calc(var(--cnvs-sys-space-x4) * 3)'
maxWidth: calc.multiply(system.space.x4, 3),
// returns 'calc(var(--cnvs-sys-padding-xxs) + 0.125rem)'
padding: calc.add(system.padding.xxs, '0.125rem'),
// returns 'calc(var(--cnvs-sys-gap-sm) - 0.125rem)'
margin: calc.subtract(system.gap.sm, '0.125rem'),
// returns 'calc(var(--cnvs-sys-size-xxxs) * 3)'
maxWidth: calc.multiply(system.size.xxxs, 3),
};
```
Loading
Loading