diff --git a/modules/docs/mdx/tokens/TokenMigrationCodemod.mdx b/modules/docs/mdx/tokens/TokenMigrationCodemod.mdx
index 594f4e1ecd..3e6b34d1f5 100644
--- a/modules/docs/mdx/tokens/TokenMigrationCodemod.mdx
+++ b/modules/docs/mdx/tokens/TokenMigrationCodemod.mdx
@@ -1,9 +1,17 @@
import {Meta} from '@storybook/blocks';
+import {StorybookInformationHighlight} from './StorybookInformationHighlight';
+
# Canvas Kit Tokens Migration Codemod
+
+
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.
diff --git a/modules/docs/mdx/tokens/TokenMigrationFinal.mdx b/modules/docs/mdx/tokens/TokenMigrationFinal.mdx
index d2653a4e66..d93aa90b82 100644
--- a/modules/docs/mdx/tokens/TokenMigrationFinal.mdx
+++ b/modules/docs/mdx/tokens/TokenMigrationFinal.mdx
@@ -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({
@@ -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,
});
```
@@ -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}`,
@@ -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,
},
});
```
@@ -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,
@@ -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,
},
});
```
diff --git a/modules/docs/mdx/tokens/TokenMigrationInstall.mdx b/modules/docs/mdx/tokens/TokenMigrationInstall.mdx
index 40d18a7758..39fdc482e2 100644
--- a/modules/docs/mdx/tokens/TokenMigrationInstall.mdx
+++ b/modules/docs/mdx/tokens/TokenMigrationInstall.mdx
@@ -1,4 +1,5 @@
import {Meta} from '@storybook/blocks';
+
import {StorybookInformationHighlight} from './StorybookInformationHighlight';
@@ -12,10 +13,10 @@ application.
@@ -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
@@ -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';
-
+
+
```
**Within Canvas styling functions**
@@ -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
})
@@ -103,7 +105,7 @@ import {cssVar} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';
```
@@ -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),
};
```
diff --git a/modules/docs/mdx/tokens/TokenMigrationMappingColors.mdx b/modules/docs/mdx/tokens/TokenMigrationMappingColors.mdx
index 868d60d940..207157f8fc 100644
--- a/modules/docs/mdx/tokens/TokenMigrationMappingColors.mdx
+++ b/modules/docs/mdx/tokens/TokenMigrationMappingColors.mdx
@@ -1,4 +1,5 @@
import {Meta} from '@storybook/blocks';
+
import {StorybookInformationHighlight} from './StorybookInformationHighlight';
@@ -36,214 +37,214 @@ to see visual changes.
> [a comparison tool](https://stackblitz.com/edit/color-comparator?file=src%2FApp.tsx) to find the
> best match.
-| Old Token | New Token | CSS Variable | System Color Replacement |
-| ------------------------------ | --------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
-| `colors.cinnamon100` | `base.red50` | `--cnvs-base-palette-red-50` | sys.color.bg.critical.softer |
-| `colors.cinnamon200` | `base.red100` | `--cnvs-base-palette-red-100` | sys.color.bg.critical.soft |
-| `colors.cinnamon300` | `base.red300` | `--cnvs-base-palette-red-300` | |
-| `colors.cinnamon400` | `base.red400` | `--cnvs-base-palette-red-400` | sys.color.fg.critical.soft |
-| `colors.cinnamon500` | `base.red600` | `--cnvs-base-palette-red-600` | sys.color.bg.critical.default
sys.color.fg.critical.default
sys.color.border.critical.default |
-| `colors.cinnamon600` | `base.red700` | `--cnvs-base-palette-red-700` | sys.color.bg.critical.strong
sys.color.fg.critical.strong |
-| `colors.peach100` | `base.coral50` | `--cnvs-base-palette-coral-50` | |
-| `colors.peach200` | `base.coral200` | `--cnvs-base-palette-coral-200` | |
-| `colors.peach300` | `base.coral300` | `--cnvs-base-palette-coral-300` | |
-| `colors.peach400` | `base.coral400` | `--cnvs-base-palette-coral-400` | |
-| `colors.peach500` | `base.coral600` | `--cnvs-base-palette-coral-600` | |
-| `colors.peach600` | `base.coral700` | `--cnvs-base-palette-coral-700` | |
-| `colors.chiliMango100` | `base.coral100` | `--cnvs-base-palette-coral-100` | |
-| `colors.chiliMango200` | `base.coral200` | `--cnvs-base-palette-coral-200` | |
-| `colors.chiliMango300` | `base.coral300` | `--cnvs-base-palette-coral-300` | |
-| `colors.chiliMango400` | `base.coral500` | `--cnvs-base-palette-coral-500` | |
-| `colors.chiliMango500` | `base.coral500` | `--cnvs-base-palette-coral-500` | |
-| `colors.chiliMango600` | `base.coral700` | `--cnvs-base-palette-coral-700` | |
-| `colors.cantaloupe100` | `base.amber50` | `--cnvs-base-palette-amber-50` | sys.color.bg.caution.softer |
-| `colors.cantaloupe200` | `base.amber200` | `--cnvs-base-palette-amber-200` | sys.color.bg.caution.soft |
-| `colors.cantaloupe300` | `base.amber300` | `--cnvs-base-palette-amber-300` | |
-| `colors.cantaloupe400` | `base.amber400` | `--cnvs-base-palette-amber-400` | sys.color.bg.caution.default
sys.color.border.caution.default |
-| `colors.cantaloupe500` | `base.amber500` | `--cnvs-base-palette-amber-500` | sys.color.bg.caution.strong
sys.color.fg.caution.softer |
-| `colors.cantaloupe600` | `base.amber600` | `--cnvs-base-palette-amber-600` | sys.color.bg.caution.stronger
sys.color.border.caution.strong |
-| `colors.sourLemon100` | `base.amber25` | `--cnvs-base-palette-amber-25` | |
-| `colors.sourLemon200` | `base.amber100` | `--cnvs-base-palette-amber-100` | |
-| `colors.sourLemon300` | `base.amber200` | `--cnvs-base-palette-amber-200` | |
-| `colors.sourLemon400` | `base.amber300` | `--cnvs-base-palette-amber-300` | |
-| `colors.sourLemon500` | `base.amber300` | `--cnvs-base-palette-amber-300` | |
-| `colors.sourLemon600` | `base.amber500` | `--cnvs-base-palette-amber-500` | |
-| `colors.juicyPear100` | `base.amber25` | `--cnvs-base-palette-amber-25` | |
-| `colors.juicyPear200` | `base.amber100` | `--cnvs-base-palette-amber-100` | |
-| `colors.juicyPear300` | `base.amber200` | `--cnvs-base-palette-amber-200` | |
-| `colors.juicyPear400` | `base.amber200` | `--cnvs-base-palette-amber-200` | |
-| `colors.juicyPear500` | `base.green500` | `--cnvs-base-palette-green-500` | |
-| `colors.juicyPear600` | `base.green700` | `--cnvs-base-palette-green-700` | |
-| `colors.kiwi100` | `base.green50` | `--cnvs-base-palette-green-50` | |
-| `colors.kiwi200` | `base.green100` | `--cnvs-base-palette-green-100` | |
-| `colors.kiwi300` | `base.green200` | `--cnvs-base-palette-green-200` | |
-| `colors.kiwi400` | `base.green500` | `--cnvs-base-palette-green-500` | |
-| `colors.kiwi500` | `base.green500` | `--cnvs-base-palette-green-500` | |
-| `colors.kiwi600` | `base.green700` | `--cnvs-base-palette-green-700` | |
-| `colors.greenApple50` | `base.green50` | `--cnvs-base-palette-green-50` | sys.color.bg.positive.softer |
-| `colors.greenApple100` | `base.green100` | `--cnvs-base-palette-green-100` | sys.color.bg.positive.soft |
-| `colors.greenApple200` | `base.green200` | `--cnvs-base-palette-green-200` | sys.color.fg.positive.soft |
-| `colors.greenApple600` | `base.green600` | `--cnvs-base-palette-green-600` | sys.color.bg.positive.default
sys.color.fg.positive.default |
-| `colors.greenApple700` | `base.green700` | `--cnvs-base-palette-green-700` | sys.color.bg.positive.strong
sys.color.fg.positive.strong |
-| `colors.greenApple800` | `base.green800` | `--cnvs-base-palette-green-800` | sys.color.bg.positive.stronger
sys.color.fg.positive.stronger |
-| `colors.watermelon100` | `base.teal25` | `--cnvs-base-palette-teal-25` | |
-| `colors.watermelon200` | `base.teal100` | `--cnvs-base-palette-teal-100` | |
-| `colors.watermelon300` | `base.green100` | `--cnvs-base-palette-green-100` | |
-| `colors.watermelon400` | `base.green600` | `--cnvs-base-palette-green-600` | |
-| `colors.watermelon500` | `base.green700` | `--cnvs-base-palette-green-700` | |
-| `colors.watermelon600` | `base.green900` | `--cnvs-base-palette-green-900` | |
-| `colors.jewel100` | `base.teal25` | `--cnvs-base-palette-teal-25` | |
-| `colors.jewel200` | `base.teal200` | `--cnvs-base-palette-teal-200` | |
-| `colors.jewel300` | `base.teal400` | `--cnvs-base-palette-teal-400` | |
-| `colors.jewel400` | `base.teal500` | `--cnvs-base-palette-teal-500` | |
-| `colors.jewel500` | `base.teal600` | `--cnvs-base-palette-teal-600` | |
-| `colors.jewel600` | `base.teal700` | `--cnvs-base-palette-teal-700` | |
-| `colors.toothpaste100` | `base.azure50` | `--cnvs-base-palette-azure-50` | |
-| `colors.toothpaste200` | `base.azure200` | `--cnvs-base-palette-azure-200` | |
-| `colors.toothpaste300` | `base.azure300` | `--cnvs-base-palette-azure-300` | |
-| `colors.toothpaste400` | `base.azure500` | `--cnvs-base-palette-azure-500` | |
-| `colors.toothpaste500` | `base.azure700` | `--cnvs-base-palette-azure-700` | |
-| `colors.toothpaste600` | `base.azure800` | `--cnvs-base-palette-azure-800` | |
-| `colors.blueberry100` | `base.blue100` | `--cnvs-base-palette-blue-100` | |
-| `colors.blueberry200` | `base.blue100` | `--cnvs-base-palette-blue-100` | sys.color.bg.primary.soft |
-| `colors.blueberry300` | `base.blue400` | `--cnvs-base-palette-blue-400` | sys.color.fg.primary.soft |
-| `colors.blueberry400` | `base.blue600` | `--cnvs-base-palette-blue-600` | sys.color.bg.primary.default
sys.color.fg.primary.default
sys.color.border.primary.default |
-| `colors.blueberry500` | `base.blue700` | `--cnvs-base-palette-blue-700` | sys.color.bg.primary.strong
sys.color.fg.primary.strong |
-| `colors.blueberry600` | `base.blue800` | `--cnvs-base-palette-blue-800` | sys.color.bg.primary.stronger
sys.color.text.primary.stronger |
-| `colors.plum100` | `base.blue100` | `--cnvs-base-palette-blue-100` | |
-| `colors.plum200` | `base.blue200` | `--cnvs-base-palette-blue-200` | |
-| `colors.plum300` | `base.blue300` | `--cnvs-base-palette-blue-300` | |
-| `colors.plum400` | `base.blue400` | `--cnvs-base-palette-blue-400` | |
-| `colors.plum500` | `base.blue500` | `--cnvs-base-palette-blue-500` | |
-| `colors.plum600` | `base.blue600` | `--cnvs-base-palette-blue-600` | |
-| `colors.berrySmoothie100` | `base.indigo50` | `--cnvs-base-palette-indigo-50` | |
-| `colors.berrySmoothie200` | `base.indigo200` | `--cnvs-base-palette-indigo-200` | |
-| `colors.berrySmoothie300` | `base.indigo400` | `--cnvs-base-palette-indigo-400` | |
-| `colors.berrySmoothie400` | `base.blue500` | `--cnvs-base-palette-blue-500` | |
-| `colors.berrySmoothie500` | `base.blue700` | `--cnvs-base-palette-blue-700` | |
-| `colors.berrySmoothie600` | `base.blue800` | `--cnvs-base-palette-blue-800` | |
-| `colors.blackberry100` | `base.indigo25` | `--cnvs-base-palette-indigo-25` | |
-| `colors.blackberry200` | `base.indigo200` | `--cnvs-base-palette-indigo-200` | |
-| `colors.blackberry300` | `base.indigo400` | `--cnvs-base-palette-indigo-400` | |
-| `colors.blackberry400` | `base.indigo500` | `--cnvs-base-palette-indigo-500` | |
-| `colors.blackberry500` | `base.indigo700` | `--cnvs-base-palette-indigo-700` | |
-| `colors.blackberry600` | `base.indigo900` | `--cnvs-base-palette-indigo-900` | |
-| `colors.islandPunch100` | `base.purple25` | `--cnvs-base-palette-purple-25` | |
-| `colors.islandPunch200` | `base.purple200` | `--cnvs-base-palette-purple-200` | |
-| `colors.islandPunch300` | `base.purple500` | `--cnvs-base-palette-purple-500` | |
-| `colors.islandPunch400` | `base.purple500` | `--cnvs-base-palette-purple-500` | |
-| `colors.islandPunch500` | `base.purple700` | `--cnvs-base-palette-purple-700` | |
-| `colors.islandPunch600` | `base.purple800` | `--cnvs-base-palette-purple-800` | |
-| `colors.grapeSoda100` | `base.magenta50` | `--cnvs-base-palette-magenta-50` | |
-| `colors.grapeSoda200` | `base.magenta200` | `--cnvs-base-palette-magenta-200` | |
-| `colors.grapeSoda300` | `base.purple400` | `--cnvs-base-palette-purple-400` | |
-| `colors.grapeSoda400` | `base.purple500` | `--cnvs-base-palette-purple-500` | |
-| `colors.grapeSoda500` | `base.purple600` | `--cnvs-base-palette-purple-600` | |
-| `colors.grapeSoda600` | `base.purple800` | `--cnvs-base-palette-purple-800` | |
-| `colors.pomegranate100` | `base.magenta50` | `--cnvs-base-palette-magenta-50` | |
-| `colors.pomegranate200` | `base.magenta100` | `--cnvs-base-palette-magenta-100` | |
-| `colors.pomegranate300` | `base.magenta500` | `--cnvs-base-palette-magenta-500` | |
-| `colors.pomegranate400` | `base.magenta400` | `--cnvs-base-palette-magenta-400` | |
-| `colors.pomegranate500` | `base.red700` | `--cnvs-base-palette-red-700` | |
-| `colors.pomegranate600` | `base.red800` | `--cnvs-base-palette-red-800` | |
-| `colors.fruitPunch100` | `base.red25` | `--cnvs-base-palette-red-25` | |
-| `colors.fruitPunch200` | `base.red200` | `--cnvs-base-palette-red-200` | |
-| `colors.fruitPunch300` | `base.red300` | `--cnvs-base-palette-red-300` | |
-| `colors.fruitPunch400` | `base.red400` | `--cnvs-base-palette-red-400` | |
-| `colors.fruitPunch500` | `base.red400` | `--cnvs-base-palette-red-400` | |
-| `colors.fruitPunch600` | `base.red700` | `--cnvs-base-palette-red-700` | |
-| `colors.rootBeer100` | `base.coral25` | `--cnvs-base-palette-coral-25` | |
-| `colors.rootBeer200` | `base.coral100` | `--cnvs-base-palette-coral-100` | |
-| `colors.rootBeer300` | `base.coral200` | `--cnvs-base-palette-coral-200` | |
-| `colors.rootBeer400` | `base.coral200` | `--cnvs-base-palette-coral-200` | |
-| `colors.rootBeer500` | `base.amber900` | `--cnvs-base-palette-amber-900` | |
-| `colors.rootBeer600` | `base.amber950` | `--cnvs-base-palette-amber-950` | |
-| `colors.toastedMarshmallow100` | `base.amber25` | `--cnvs-base-palette-amber-25` | |
-| `colors.toastedMarshmallow200` | `base.orange100` | `--cnvs-base-palette-orange-100` | |
-| `colors.toastedMarshmallow300` | `base.orange200` | `--cnvs-base-palette-orange-200` | |
-| `colors.toastedMarshmallow400` | `base.orange300` | `--cnvs-base-palette-orange-300` | |
-| `colors.toastedMarshmallow500` | `base.amber500` | `--cnvs-base-palette-amber-500` | |
-| `colors.toastedMarshmallow600` | `base.amber600` | `--cnvs-base-palette-amber-600` | |
-| `colors.licorice100` | `base.slate400` | `--cnvs-base-palette-slate-400` | sys.color.bg.muted.softer
sys.color.fg.disabled
sys.color.border.input.disabled |
-| `colors.licorice200` | `base.slate500` | `--cnvs-base-palette-slate-500` | sys.color.bg.muted.soft
sys.color.fg.muted.soft
sys.color.border.input.default |
-| `colors.licorice300` | `base.slate600` | `--cnvs-base-palette-slate-600` | sys.color.bg.muted.default
sys.color.fg.muted.default
sys.color.text.hint |
-| `colors.licorice400` | `base.slate700` | `--cnvs-base-palette-slate-700` | sys.color.fg.muted.strong |
-| `colors.licorice500` | `base.slate800` | `--cnvs-base-palette-slate-800` | sys.color.bg.muted.strong
sys.color.fg.muted.stronger
sys.color.border.input.strong |
-| `colors.licorice600` | `base.slate900` | `--cnvs-base-palette-slate-900` | |
-| `colors.blackPepper100` | `base.neutral500` | `--cnvs-base-palette-neutral-500` | |
-| `colors.blackPepper200` | `base.neutral700` | `--cnvs-base-palette-neutral-700` | |
-| `colors.blackPepper300` | `base.neutral900` | `--cnvs-base-palette-neutral-900` | sys.color.fg.default |
-| `colors.blackPepper400` | `base.neutral950` | `--cnvs-base-palette-neutral-950` | sys.color.bg.contrast.default
sys.color.fg.strong
sys.color.border.contrast.default |
-| `colors.blackPepper500` | `base.neutral975` | `--cnvs-base-palette-neutral-975` | sys.color.bg.contrast.strong
sys.color.fg.stronger
sys.color.border.contrast.strong |
-| `colors.blackPepper600` | `base.neutral1000` | `--cnvs-base-palette-neutral-1000` | |
-| `colors.frenchVanilla100` | `base.neutral0` | `--cnvs-base-palette-neutral-0` | sys.color.bg.default
sys.color.fg.inverse
sys.color.border.inverse |
-| `colors.frenchVanilla200` | `base.neutral100` | `--cnvs-base-palette-neutral-100` | |
-| `colors.frenchVanilla300` | `base.neutral200` | `--cnvs-base-palette-neutral-200` | |
-| `colors.frenchVanilla400` | `base.neutral300` | `--cnvs-base-palette-neutral-300` | |
-| `colors.frenchVanilla500` | `base.neutral400` | `--cnvs-base-palette-neutral-400` | |
-| `colors.frenchVanilla600` | `base.neutral500` | `--cnvs-base-palette-neutral-500` | |
-| `colors.soap100` | `base.slate25` | `--cnvs-base-palette-slate-25` | sys.color.bg.alt.softer |
-| `colors.soap200` | `base.slate50` | `--cnvs-base-palette-slate-50` | sys.color.bg.alt.soft |
-| `colors.soap300` | `base.slate100` | `--cnvs-base-palette-slate-100` | sys.color.bg.alt.default
sys.color.border.input.inverse |
-| `colors.soap400` | `base.slate200` | `--cnvs-base-palette-slate-200` | sys.color.bg.alt.strong
sys.color.border.divider |
-| `colors.soap500` | `base.slate300` | `--cnvs-base-palette-slate-300` | sys.color.bg.alt.stronger
sys.color.border.container |
-| `colors.soap600` | `base.slate300` | `--cnvs-base-palette-slate-300` | |
-| `colors.coconut100` | `base.coconut100` (deprecated) | `--cnvs-base-palette-coconut-100` | |
-| `colors.coconut200` | `base.coconut200` (deprecated) | `--cnvs-base-palette-coconut-200` | |
-| `colors.coconut300` | `base.coconut300` (deprecated) | `--cnvs-base-palette-coconut-300` | |
-| `colors.coconut400` | `base.coconut400` (deprecated) | `--cnvs-base-palette-coconut-400` | |
-| `colors.coconut500` | `base.coconut500` (deprecated) | `--cnvs-base-palette-coconut-500` | |
-| `colors.coconut600` | `base.coconut600` (deprecated) | `--cnvs-base-palette-coconut-600` | |
-| `colors.cappuccino100` | `base.cappuccino100` (deprecated) | `--cnvs-base-palette-cappuccino-100` | |
-| `colors.cappuccino200` | `base.cappuccino200` (deprecated) | `--cnvs-base-palette-cappuccino-200` | |
-| `colors.cappuccino300` | `base.cappuccino300` (deprecated) | `--cnvs-base-palette-cappuccino-300` | |
-| `colors.cappuccino400` | `base.cappuccino400` (deprecated) | `--cnvs-base-palette-cappuccino-400` | |
-| `colors.cappuccino500` | `base.cappuccino500` (deprecated) | `--cnvs-base-palette-cappuccino-500` | |
-| `colors.cappuccino600` | `base.cappuccino600` (deprecated) | `--cnvs-base-palette-cappuccino-600` | |
-| `colors.dragonFruit100` | `base.purple25` | `--cnvs-base-palette-purple-25` | |
-| `colors.dragonFruit200` | `base.purple100` | `--cnvs-base-palette-purple-100` | |
-| `colors.dragonFruit300` | `base.indigo500` | `--cnvs-base-palette-indigo-500` | |
-| `colors.dragonFruit400` | `base.indigo600` | `--cnvs-base-palette-indigo-600` | |
-| `colors.dragonFruit500` | `base.indigo700` | `--cnvs-base-palette-indigo-700` | |
-| `colors.dragonFruit600` | `base.indigo800` | `--cnvs-base-palette-indigo-800` | |
+| Old Token | New Token | CSS Variable | Surface System Color | Foreground System Color | Border System Color |
+| ------------------------------ | --------------------------------- | ------------------------------------ | --------------------------------------------- | ---------------------------------------- | ---------------------------------------- |
+| `colors.cinnamon100` | `base.red50` | `--cnvs-base-palette-red-50` | `system.color.brand.surface.critical.strong` | `system.color.fg.danger.default` | |
+| `colors.cinnamon200` | `base.red100` | `--cnvs-base-palette-red-100` | `system.color.surface.danger.default` | | |
+| `colors.cinnamon300` | `base.red300` | `--cnvs-base-palette-red-300` | | | |
+| `colors.cinnamon400` | `base.red400` | `--cnvs-base-palette-red-400` | | `system.color.fg.danger.default` | |
+| `colors.cinnamon500` | `base.red600` | `--cnvs-base-palette-red-600` | `system.color.brand.accent.critical` | `system.color.brand.fg.critical.default` | `system.color.border.critical.default` |
+| `colors.cinnamon600` | `base.red700` | `--cnvs-base-palette-red-700` | `system.color.fg.danger.strong` | `system.color.fg.critical.strong` | |
+| `colors.peach100` | `base.coral50` | `--cnvs-base-palette-coral-50` | | | |
+| `colors.peach200` | `base.coral200` | `--cnvs-base-palette-coral-200` | | | |
+| `colors.peach300` | `base.coral300` | `--cnvs-base-palette-coral-300` | | | |
+| `colors.peach400` | `base.coral400` | `--cnvs-base-palette-coral-400` | | | |
+| `colors.peach500` | `base.coral600` | `--cnvs-base-palette-coral-600` | | | |
+| `colors.peach600` | `base.coral700` | `--cnvs-base-palette-coral-700` | | | |
+| `colors.chiliMango100` | `base.coral100` | `--cnvs-base-palette-coral-100` | | | |
+| `colors.chiliMango200` | `base.coral200` | `--cnvs-base-palette-coral-200` | | | |
+| `colors.chiliMango300` | `base.coral300` | `--cnvs-base-palette-coral-300` | | | |
+| `colors.chiliMango400` | `base.coral500` | `--cnvs-base-palette-coral-500` | | | |
+| `colors.chiliMango500` | `base.coral500` | `--cnvs-base-palette-coral-500` | | | |
+| `colors.chiliMango600` | `base.coral700` | `--cnvs-base-palette-coral-700` | | | |
+| `colors.cantaloupe100` | `base.amber50` | `--cnvs-base-palette-amber-50` | `system.color.brand.surface.caution.strong` | | |
+| `colors.cantaloupe200` | `base.amber200` | `--cnvs-base-palette-amber-200` | `system.color.surface.warning.default` | | |
+| `colors.cantaloupe300` | `base.amber300` | `--cnvs-base-palette-amber-300` | | | |
+| `colors.cantaloupe400` | `base.amber400` | `--cnvs-base-palette-amber-400` | `system.color.brand.accent.caution` | | `system.color.brand.focus.caution.inner` |
+| `colors.cantaloupe500` | `base.amber500` | `--cnvs-base-palette-amber-500` | `system.color.brand.accent.caution` | `system.color.fg.warning.default` | |
+| `colors.cantaloupe600` | `base.amber600` | `--cnvs-base-palette-amber-600` | `system.color.brand.accent.caution` | | `system.color.brand.focus.caution.outer` |
+| `colors.sourLemon100` | `base.amber25` | `--cnvs-base-palette-amber-25` | | | |
+| `colors.sourLemon200` | `base.amber100` | `--cnvs-base-palette-amber-100` | | | |
+| `colors.sourLemon300` | `base.amber200` | `--cnvs-base-palette-amber-200` | | | |
+| `colors.sourLemon400` | `base.amber300` | `--cnvs-base-palette-amber-300` | | | |
+| `colors.sourLemon500` | `base.amber300` | `--cnvs-base-palette-amber-300` | | | |
+| `colors.sourLemon600` | `base.amber500` | `--cnvs-base-palette-amber-500` | | | |
+| `colors.juicyPear100` | `base.amber25` | `--cnvs-base-palette-amber-25` | | | |
+| `colors.juicyPear200` | `base.amber100` | `--cnvs-base-palette-amber-100` | | | |
+| `colors.juicyPear300` | `base.amber200` | `--cnvs-base-palette-amber-200` | | | |
+| `colors.juicyPear400` | `base.amber200` | `--cnvs-base-palette-amber-200` | | | |
+| `colors.juicyPear500` | `base.green500` | `--cnvs-base-palette-green-500` | | | |
+| `colors.juicyPear600` | `base.green700` | `--cnvs-base-palette-green-700` | | | |
+| `colors.kiwi100` | `base.green50` | `--cnvs-base-palette-green-50` | | | |
+| `colors.kiwi200` | `base.green100` | `--cnvs-base-palette-green-100` | | | |
+| `colors.kiwi300` | `base.green200` | `--cnvs-base-palette-green-200` | | | |
+| `colors.kiwi400` | `base.green500` | `--cnvs-base-palette-green-500` | | | |
+| `colors.kiwi500` | `base.green500` | `--cnvs-base-palette-green-500` | | | |
+| `colors.kiwi600` | `base.green700` | `--cnvs-base-palette-green-700` | | | |
+| `colors.greenApple50` | `base.green50` | `--cnvs-base-palette-green-50` | `system.color.brand.surface.positive.strong` | | |
+| `colors.greenApple100` | `base.green100` | `--cnvs-base-palette-green-100` | `system.color.brand.surface.positive.default` | | |
+| `colors.greenApple200` | `base.green200` | `--cnvs-base-palette-green-200` | | `system.color.fg.success.default` | |
+| `colors.greenApple600` | `base.green600` | `--cnvs-base-palette-green-600` | `system.color.accent.success.default` | `system.color.brand.fg.positive.default` | |
+| `colors.greenApple700` | `base.green700` | `--cnvs-base-palette-green-700` | `system.color.brand.accent.positive` | `system.color.brand.fg.positive.strong` | |
+| `colors.greenApple800` | `base.green800` | `--cnvs-base-palette-green-800` | `system.color.brand.accent.positive` | `system.color.brand.fg.positive.strong` | |
+| `colors.watermelon100` | `base.teal25` | `--cnvs-base-palette-teal-25` | | | |
+| `colors.watermelon200` | `base.teal100` | `--cnvs-base-palette-teal-100` | | | |
+| `colors.watermelon300` | `base.green100` | `--cnvs-base-palette-green-100` | | | |
+| `colors.watermelon400` | `base.green600` | `--cnvs-base-palette-green-600` | | | |
+| `colors.watermelon500` | `base.green700` | `--cnvs-base-palette-green-700` | | | |
+| `colors.watermelon600` | `base.green900` | `--cnvs-base-palette-green-900` | | | |
+| `colors.jewel100` | `base.teal25` | `--cnvs-base-palette-teal-25` | | | |
+| `colors.jewel200` | `base.teal200` | `--cnvs-base-palette-teal-200` | | | |
+| `colors.jewel300` | `base.teal400` | `--cnvs-base-palette-teal-400` | | | |
+| `colors.jewel400` | `base.teal500` | `--cnvs-base-palette-teal-500` | | | |
+| `colors.jewel500` | `base.teal600` | `--cnvs-base-palette-teal-600` | | | |
+| `colors.jewel600` | `base.teal700` | `--cnvs-base-palette-teal-700` | | | |
+| `colors.toothpaste100` | `base.azure50` | `--cnvs-base-palette-azure-50` | | | |
+| `colors.toothpaste200` | `base.azure200` | `--cnvs-base-palette-azure-200` | | | |
+| `colors.toothpaste300` | `base.azure300` | `--cnvs-base-palette-azure-300` | | | |
+| `colors.toothpaste400` | `base.azure500` | `--cnvs-base-palette-azure-500` | | | |
+| `colors.toothpaste500` | `base.azure700` | `--cnvs-base-palette-azure-700` | | | |
+| `colors.toothpaste600` | `base.azure800` | `--cnvs-base-palette-azure-800` | | | |
+| `colors.blueberry100` | `base.blue100` | `--cnvs-base-palette-blue-100` | | | |
+| `colors.blueberry200` | `base.blue100` | `--cnvs-base-palette-blue-100` | `system.color.brand.surface.primary.default` | | |
+| `colors.blueberry300` | `base.blue400` | `--cnvs-base-palette-blue-400` | | `system.color.fg.info.default` | |
+| `colors.blueberry400` | `base.blue600` | `--cnvs-base-palette-blue-600` | `system.color.brand.accent.primary` | `system.color.brand.fg.primary.default` | `system.color.border.primary.default` |
+| `colors.blueberry500` | `base.blue700` | `--cnvs-base-palette-blue-700` | `system.color.brand.accent.primary` | `system.color.brand.fg.primary.strong` | |
+| `colors.blueberry600` | `base.blue800` | `--cnvs-base-palette-blue-800` | `system.color.brand.accent.primary` | `system.color.brand.fg.primary.strong` | |
+| `colors.plum100` | `base.blue100` | `--cnvs-base-palette-blue-100` | | | |
+| `colors.plum200` | `base.blue200` | `--cnvs-base-palette-blue-200` | | | |
+| `colors.plum300` | `base.blue300` | `--cnvs-base-palette-blue-300` | | | |
+| `colors.plum400` | `base.blue400` | `--cnvs-base-palette-blue-400` | | | |
+| `colors.plum500` | `base.blue500` | `--cnvs-base-palette-blue-500` | | | |
+| `colors.plum600` | `base.blue600` | `--cnvs-base-palette-blue-600` | | | |
+| `colors.berrySmoothie100` | `base.indigo50` | `--cnvs-base-palette-indigo-50` | | | |
+| `colors.berrySmoothie200` | `base.indigo200` | `--cnvs-base-palette-indigo-200` | | | |
+| `colors.berrySmoothie300` | `base.indigo400` | `--cnvs-base-palette-indigo-400` | | | |
+| `colors.berrySmoothie400` | `base.blue500` | `--cnvs-base-palette-blue-500` | | | |
+| `colors.berrySmoothie500` | `base.blue700` | `--cnvs-base-palette-blue-700` | | | |
+| `colors.berrySmoothie600` | `base.blue800` | `--cnvs-base-palette-blue-800` | | | |
+| `colors.blackberry100` | `base.indigo25` | `--cnvs-base-palette-indigo-25` | | | |
+| `colors.blackberry200` | `base.indigo200` | `--cnvs-base-palette-indigo-200` | | | |
+| `colors.blackberry300` | `base.indigo400` | `--cnvs-base-palette-indigo-400` | | | |
+| `colors.blackberry400` | `base.indigo500` | `--cnvs-base-palette-indigo-500` | | | |
+| `colors.blackberry500` | `base.indigo700` | `--cnvs-base-palette-indigo-700` | | | |
+| `colors.blackberry600` | `base.indigo900` | `--cnvs-base-palette-indigo-900` | | | |
+| `colors.islandPunch100` | `base.purple25` | `--cnvs-base-palette-purple-25` | | | |
+| `colors.islandPunch200` | `base.purple200` | `--cnvs-base-palette-purple-200` | | | |
+| `colors.islandPunch300` | `base.purple500` | `--cnvs-base-palette-purple-500` | | | |
+| `colors.islandPunch400` | `base.purple500` | `--cnvs-base-palette-purple-500` | | | |
+| `colors.islandPunch500` | `base.purple700` | `--cnvs-base-palette-purple-700` | | | |
+| `colors.islandPunch600` | `base.purple800` | `--cnvs-base-palette-purple-800` | | | |
+| `colors.grapeSoda100` | `base.magenta50` | `--cnvs-base-palette-magenta-50` | | | |
+| `colors.grapeSoda200` | `base.magenta200` | `--cnvs-base-palette-magenta-200` | | | |
+| `colors.grapeSoda300` | `base.purple400` | `--cnvs-base-palette-purple-400` | | | |
+| `colors.grapeSoda400` | `base.purple500` | `--cnvs-base-palette-purple-500` | | | |
+| `colors.grapeSoda500` | `base.purple600` | `--cnvs-base-palette-purple-600` | | | |
+| `colors.grapeSoda600` | `base.purple800` | `--cnvs-base-palette-purple-800` | | | |
+| `colors.pomegranate100` | `base.magenta50` | `--cnvs-base-palette-magenta-50` | | | |
+| `colors.pomegranate200` | `base.magenta100` | `--cnvs-base-palette-magenta-100` | | | |
+| `colors.pomegranate300` | `base.magenta500` | `--cnvs-base-palette-magenta-500` | | | |
+| `colors.pomegranate400` | `base.magenta400` | `--cnvs-base-palette-magenta-400` | | | |
+| `colors.pomegranate500` | `base.red700` | `--cnvs-base-palette-red-700` | | | |
+| `colors.pomegranate600` | `base.red800` | `--cnvs-base-palette-red-800` | | | |
+| `colors.fruitPunch100` | `base.red25` | `--cnvs-base-palette-red-25` | | | |
+| `colors.fruitPunch200` | `base.red200` | `--cnvs-base-palette-red-200` | | | |
+| `colors.fruitPunch300` | `base.red300` | `--cnvs-base-palette-red-300` | | | |
+| `colors.fruitPunch400` | `base.red400` | `--cnvs-base-palette-red-400` | | | |
+| `colors.fruitPunch500` | `base.red400` | `--cnvs-base-palette-red-400` | | | |
+| `colors.fruitPunch600` | `base.red700` | `--cnvs-base-palette-red-700` | | | |
+| `colors.rootBeer100` | `base.coral25` | `--cnvs-base-palette-coral-25` | | | |
+| `colors.rootBeer200` | `base.coral100` | `--cnvs-base-palette-coral-100` | | | |
+| `colors.rootBeer300` | `base.coral200` | `--cnvs-base-palette-coral-200` | | | |
+| `colors.rootBeer400` | `base.coral200` | `--cnvs-base-palette-coral-200` | | | |
+| `colors.rootBeer500` | `base.amber900` | `--cnvs-base-palette-amber-900` | | | |
+| `colors.rootBeer600` | `base.amber950` | `--cnvs-base-palette-amber-950` | | | |
+| `colors.toastedMarshmallow100` | `base.amber25` | `--cnvs-base-palette-amber-25` | | | |
+| `colors.toastedMarshmallow200` | `base.orange100` | `--cnvs-base-palette-orange-100` | | | |
+| `colors.toastedMarshmallow300` | `base.orange200` | `--cnvs-base-palette-orange-200` | | | |
+| `colors.toastedMarshmallow400` | `base.orange300` | `--cnvs-base-palette-orange-300` | | | |
+| `colors.toastedMarshmallow500` | `base.amber500` | `--cnvs-base-palette-amber-500` | | | |
+| `colors.toastedMarshmallow600` | `base.amber600` | `--cnvs-base-palette-amber-600` | | | |
+| `colors.licorice100` | `base.slate400` | `--cnvs-base-palette-slate-400` | `system.color.accent.muted.soft` | `system.color.fg.disabled` | `system.color.fg.disabled` |
+| `colors.licorice200` | `base.slate500` | `--cnvs-base-palette-slate-500` | `system.color.accent.muted.soft` | `system.color.fg.muted.default` | `system.color.border.input.default` |
+| `colors.licorice300` | `base.slate600` | `--cnvs-base-palette-slate-600` | `system.color.accent.muted.default` | `system.color.fg.muted.default` | |
+| `colors.licorice400` | `base.slate700` | `--cnvs-base-palette-slate-700` | `system.color.accent.muted.default` | `system.color.fg.muted.strong ` |
+| `colors.licorice500` | `base.slate800` | `--cnvs-base-palette-slate-800` | `system.color.accent.muted.default` | `system.color.fg.muted.strong ` | `system.color.border.input.hover` |
+| `colors.licorice600` | `base.slate900` | `--cnvs-base-palette-slate-900` | | | |
+| `colors.blackPepper100` | `base.neutral500` | `--cnvs-base-palette-neutral-500` | | | |
+| `colors.blackPepper200` | `base.neutral700` | `--cnvs-base-palette-neutral-700` | | | |
+| `colors.blackPepper300` | `base.neutral900` | `--cnvs-base-palette-neutral-900` | | `system.color.fg.default` | |
+| `colors.blackPepper400` | `base.neutral950` | `--cnvs-base-palette-neutral-950` | `system.color.surface.contrast.default ` | `system.color.fg.strong` | `system.color.border.contrast.default` |
+| `colors.blackPepper500` | `base.neutral975` | `--cnvs-base-palette-neutral-975` | `system.color.surface.contrast.strong` | `system.color.fg.stronger` | `system.color.border.contrast.strong` |
+| `colors.blackPepper600` | `base.neutral1000` | `--cnvs-base-palette-neutral-1000` | | | |
+| `colors.frenchVanilla100` | `base.neutral0` | `--cnvs-base-palette-neutral-0` | `system.color.surface.default` | `system.color.fg.inverse` | `system.color.border.inverse` |
+| `colors.frenchVanilla200` | `base.neutral100` | `--cnvs-base-palette-neutral-100` | | | |
+| `colors.frenchVanilla300` | `base.neutral200` | `--cnvs-base-palette-neutral-200` | | | |
+| `colors.frenchVanilla400` | `base.neutral300` | `--cnvs-base-palette-neutral-300` | | | |
+| `colors.frenchVanilla500` | `base.neutral400` | `--cnvs-base-palette-neutral-400` | | | |
+| `colors.frenchVanilla600` | `base.neutral500` | `--cnvs-base-palette-neutral-500` | | | |
+| `colors.soap100` | `base.slate25` | `--cnvs-base-palette-slate-25` | `system.color.surface.raised` | | |
+| `colors.soap200` | `base.slate50` | `--cnvs-base-palette-slate-50` | `system.color.surface.alt.default` | | |
+| `colors.soap300` | `base.slate100` | `--cnvs-base-palette-slate-100` | `system.color.surface.alt.default` | `system.color.border.input.inverse` | |
+| `colors.soap400` | `base.slate200` | `--cnvs-base-palette-slate-200` | `system.color.surface.alt.default` | `system.color.border.default` | |
+| `colors.soap500` | `base.slate300` | `--cnvs-base-palette-slate-300` | `system.color.surface.alt.default` | `system.color.border.strong` | |
+| `colors.soap600` | `base.slate300` | `--cnvs-base-palette-slate-300` | | | |
+| `colors.coconut100` | `base.coconut100` (deprecated) | `--cnvs-base-palette-coconut-100` | | | |
+| `colors.coconut200` | `base.coconut200` (deprecated) | `--cnvs-base-palette-coconut-200` | | | |
+| `colors.coconut300` | `base.coconut300` (deprecated) | `--cnvs-base-palette-coconut-300` | | | |
+| `colors.coconut400` | `base.coconut400` (deprecated) | `--cnvs-base-palette-coconut-400` | | | |
+| `colors.coconut500` | `base.coconut500` (deprecated) | `--cnvs-base-palette-coconut-500` | | | |
+| `colors.coconut600` | `base.coconut600` (deprecated) | `--cnvs-base-palette-coconut-600` | | | |
+| `colors.cappuccino100` | `base.cappuccino100` (deprecated) | `--cnvs-base-palette-cappuccino-100` | | | |
+| `colors.cappuccino200` | `base.cappuccino200` (deprecated) | `--cnvs-base-palette-cappuccino-200` | | | |
+| `colors.cappuccino300` | `base.cappuccino300` (deprecated) | `--cnvs-base-palette-cappuccino-300` | | | |
+| `colors.cappuccino400` | `base.cappuccino400` (deprecated) | `--cnvs-base-palette-cappuccino-400` | | | |
+| `colors.cappuccino500` | `base.cappuccino500` (deprecated) | `--cnvs-base-palette-cappuccino-500` | | | |
+| `colors.cappuccino600` | `base.cappuccino600` (deprecated) | `--cnvs-base-palette-cappuccino-600` | | | |
+| `colors.dragonFruit100` | `base.purple25` | `--cnvs-base-palette-purple-25` | | | |
+| `colors.dragonFruit200` | `base.purple100` | `--cnvs-base-palette-purple-100` | | | |
+| `colors.dragonFruit300` | `base.indigo500` | `--cnvs-base-palette-indigo-500` | | | |
+| `colors.dragonFruit400` | `base.indigo600` | `--cnvs-base-palette-indigo-600` | | | |
+| `colors.dragonFruit500` | `base.indigo700` | `--cnvs-base-palette-indigo-700` | | | |
+| `colors.dragonFruit600` | `base.indigo800` | `--cnvs-base-palette-indigo-800` | | | |
## Brand Color Migration
Brand colors move from the Emotion theme object to direct CSS variables:
-| Old Token | New Token | CSS Variable |
-| ------------------------------------------ | --------------------------- | ----------------------------------- |
-| `theme.canvas.palette.primary.lightest` | `brand.primary.lightest` | `--cnvs-brand-primary-lightest` |
-| `theme.canvas.palette.primary.light` | `brand.primary.light` | `--cnvs-brand-primary-light` |
-| `theme.canvas.palette.primary.main` | `brand.primary.base` | `--cnvs-brand-primary-base` |
-| `theme.canvas.palette.primary.dark` | `brand.primary.dark` | `--cnvs-brand-primary-dark` |
-| `theme.canvas.palette.primary.darkest` | `brand.primary.darkest` | `--cnvs-brand-primary-darkest` |
-| `theme.canvas.palette.primary.contrast` | `brand.primary.accent` | `--cnvs-brand-primary-accent` |
-| `theme.canvas.palette.error.lightest` | `brand.error.lightest` | `--cnvs-brand-error-lightest` |
-| `theme.canvas.palette.error.light` | `brand.error.light` | `--cnvs-brand-error-light` |
-| `theme.canvas.palette.error.main` | `brand.error.base` | `--cnvs-brand-error-base` |
-| `theme.canvas.palette.error.dark` | `brand.error.dark` | `--cnvs-brand-error-dark` |
-| `theme.canvas.palette.error.darkest` | `brand.error.darkest` | `--cnvs-brand-error-darkest` |
-| `theme.canvas.palette.error.contrast` | `brand.error.accent` | `--cnvs-brand-error-accent` |
-| `theme.canvas.palette.alert.lightest` | `brand.alert.lightest` | `--cnvs-brand-alert-lightest` |
-| `theme.canvas.palette.alert.light` | `brand.alert.light` | `--cnvs-brand-alert-light` |
-| `theme.canvas.palette.alert.main` | `brand.alert.base` | `--cnvs-brand-alert-base` |
-| `theme.canvas.palette.alert.dark` | `brand.alert.dark` | `--cnvs-brand-alert-dark` |
-| `theme.canvas.palette.alert.darkest` | `brand.alert.darkest` | `--cnvs-brand-alert-darkest` |
-| `theme.canvas.palette.alert.contrast` | `brand.alert.accent` | `--cnvs-brand-alert-accent` |
-| `theme.canvas.palette.success.lightest` | `brand.success.lightest` | `--cnvs-brand-success-lightest` |
-| `theme.canvas.palette.success.light` | `brand.success.light` | `--cnvs-brand-success-light` |
-| `theme.canvas.palette.success.main` | `brand.success.base` | `--cnvs-brand-success-base` |
-| `theme.canvas.palette.success.dark` | `brand.success.dark` | `--cnvs-brand-success-dark` |
-| `theme.canvas.palette.success.darkest` | `brand.success.darkest` | `--cnvs-brand-success-darkest` |
-| `theme.canvas.palette.success.contrast` | `brand.success.accent` | `--cnvs-brand-success-accent` |
-| `theme.canvas.palette.neutral.lightest` | `brand.neutral.lightest` | `--cnvs-brand-neutral-lightest` |
-| `theme.canvas.palette.neutral.light` | `brand.neutral.light` | `--cnvs-brand-neutral-light` |
-| `theme.canvas.palette.neutral.main` | `brand.neutral.base` | `--cnvs-brand-neutral-base` |
-| `theme.canvas.palette.neutral.dark` | `brand.neutral.dark` | `--cnvs-brand-neutral-dark` |
-| `theme.canvas.palette.neutral.darkest` | `brand.neutral.darkest` | `--cnvs-brand-neutral-darkest` |
-| `theme.canvas.palette.neutral.contrast` | `brand.neutral.accent` | `--cnvs-brand-neutral-accent` |
-| `theme.canvas.palette.common.focusOutline` | `brand.common.focusOutline` | `--cnvs-brand-common-focus-outline` |
+| Old Token | v3 Token | v4 New Token | CSS Variable |
+| ------------------------------------------ | :-------------------------: | :-----------------------: | --------------------------- |
+| `theme.canvas.palette.primary.lightest` | `brand.primary.lightest` | `brand.primary25` | `--cnvs-brand-primary-25` |
+| `theme.canvas.palette.primary.light` | `brand.primary.light` | `brand.primary200` | `--cnvs-brand-primary-200` |
+| `theme.canvas.palette.primary.main` | `brand.primary.base` | `brand.primary600` | `--cnvs-brand-primary-600` |
+| `theme.canvas.palette.primary.dark` | `brand.primary.dark` | `brand.primary700` | `--cnvs-brand-primary-700` |
+| `theme.canvas.palette.primary.darkest` | `brand.primary.darkest` | `brand.primary800` | `--cnvs-brand-primary-800` |
+| `theme.canvas.palette.primary.contrast` | `brand.primary.accent` | `system.color.fg.inverse` | `--cnvs-brand-fg-inverse` |
+| `theme.canvas.palette.error.lightest` | `brand.error.lightest` | `brand.critical25` | `--cnvs-brand-error-25` |
+| `theme.canvas.palette.error.light` | `brand.error.light` | `brand.critical200` | `--cnvs-brand-error-200` |
+| `theme.canvas.palette.error.main` | `brand.error.base` | `brand.critical600` | `--cnvs-brand-error-600` |
+| `theme.canvas.palette.error.dark` | `brand.error.dark` | `brand.critical700` | `--cnvs-brand-error-700` |
+| `theme.canvas.palette.error.darkest` | `brand.error.darkest` | `brand.critical800` | `--cnvs-brand-error-800` |
+| `theme.canvas.palette.error.contrast` | `brand.error.accent` | `system.color.fg.inverse` | `--cnvs-brand-fg-inverse` |
+| `theme.canvas.palette.alert.lightest` | `brand.alert.lightest` | `brand.caution.5` | `--cnvs-brand-alert-25` |
+| `theme.canvas.palette.alert.light` | `brand.alert.light` | `brand.caution200` | `--cnvs-brand-alert-200` |
+| `theme.canvas.palette.alert.main` | `brand.alert.base` | `brand.caution600` | `--cnvs-brand-alert-600` |
+| `theme.canvas.palette.alert.dark` | `brand.alert.dark` | `brand.caution700` | `--cnvs-brand-alert-700` |
+| `theme.canvas.palette.alert.darkest` | `brand.alert.darkest` | `brand.caution800` | `--cnvs-brand-alert-800` |
+| `theme.canvas.palette.alert.contrast` | `brand.alert.accent` | `system.color.fg.inverse` | `--cnvs-brand-fg-inverse` |
+| `theme.canvas.palette.success.lightest` | `brand.success.lightest` | `brand.positive25` | `--cnvs-brand-success-25` |
+| `theme.canvas.palette.success.light` | `brand.success.light` | `brand.positive200` | `--cnvs-brand-success-200` |
+| `theme.canvas.palette.success.main` | `brand.success.base` | `brand.positive600` | `--cnvs-brand-success-600` |
+| `theme.canvas.palette.success.dark` | `brand.success.dark` | `brand.positive700` | `--cnvs-brand-success-700` |
+| `theme.canvas.palette.success.darkest` | `brand.success.darkest` | `brand.positive800` | `--cnvs-brand-success-800` |
+| `theme.canvas.palette.success.contrast` | `brand.success.accent` | `system.color.fg.inverse` | `--cnvs-brand-fg-inverse` |
+| `theme.canvas.palette.neutral.lightest` | `brand.neutral.lightest` | `brand.neutral25` | `--cnvs-brand-neutral-25` |
+| `theme.canvas.palette.neutral.light` | `brand.neutral.light` | `brand.neutral200` | `--cnvs-brand-neutral-200` |
+| `theme.canvas.palette.neutral.main` | `brand.neutral.base` | `brand.neutral600` | `--cnvs-brand-neutral-600` |
+| `theme.canvas.palette.neutral.dark` | `brand.neutral.dark` | `brand.neutral700` | `--cnvs-brand-neutral-700` |
+| `theme.canvas.palette.neutral.darkest` | `brand.neutral.darkest` | `brand.neutral800` | `--cnvs-brand-neutral-800` |
+| `theme.canvas.palette.neutral.contrast` | `brand.neutral.accent` | `system.color.fg.inverse` | `--cnvs-brand-fg-inverse` |
+| `theme.canvas.palette.common.focusOutline` | `brand.common.focusOutline` | `brand.common.focus` | `--cnvs-brand-common-focus` |
## System Color Usage Guide (Recommended)
@@ -251,77 +252,78 @@ Brand colors move from the Emotion theme object to direct CSS variables:
UI. Instead of referencing raw base colors, use these system tokens to ensure your application is
themeable, understandable, and consistent.**
-- **Background (`system.color.bg.*`)**: For all surface and container backgrounds, including pages,
- cards, banners, and input fields. Choose the appropriate variant (`default`, `soft`, `strong`,
- etc.) based on the visual prominence and interaction state (default, hover, active, disabled).
-- **Foreground (`system.color.fg.*`)**: For text and icon colors. Use variants for body text,
- headings, links, disabled states, and inverse (light-on-dark) content.
-- **Border (`system.color.border.*`)**: For outlines, dividers, and input borders. Select the
- variant that matches the required emphasis or interaction state.
+- **Surface/background (`system.color.surface.*`, `system.color.brand.surface.*`,
+ `system.color.accent.*`)**: For all surface and container backgrounds, including pages, cards,
+ banners, and input fields. Choose the appropriate variant based on the visual prominence and
+ interaction state (default, hover, active, disabled).
+- **Foreground (`system.color.fg.*`, `system.color.brand.fg.*`)**: For text and icon colors. Use
+ variants for body text, headings, links, disabled states, and inverse (light-on-dark) content.
+- **Border (`system.color.border.*`, `system.color.brand.focus.*`)**: For outlines, dividers, and
+ input borders. Select the variant that matches the required emphasis or interaction state.
### Background colors
-| Use Case | System Token | Old Token / React tokens | Example Usage |
-| -------------------------------------- | :------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------: | ---------------------------------------- |
-| **Background Colors** | | | |
-| Main page background | `system.color.bg.default` | `colors.frenchVanilla100`
`inputColors.background`
`commonColors.background` | Page layout base background |
-| Disabled elements | `system.color.bg.primary.soft` | `colors.blueberry200` | Disabled primary buttons |
-| Brand default background | `system.color.bg.primary.default` | `colors.blueberry400`
`commonColors.focusBackground`
`inputColors.selectionControlFill` | Brand banners, primary button background |
-| Brand hover background | `system.color.bg.primary.strong` | `colors.blueberry500` | Primary button hover |
-| Brand active background | `system.color.bg.primary.stronger` | `colors.blueberry600` | Primary button active |
-| Warning subtle background | `system.color.bg.caution.softer` | `colors.cantaloupe100` | Soft warning banners |
-| Warning default background | `system.color.bg.caution.default` | `colors.cantaloupe400` | Toast notifications |
-| Warning hover background | `system.color.bg.caution.strong` | `colors.cantaloupe500` | Warning hover states |
-| Warning active background | `system.color.bg.caution.stronger` | `colors.cantaloupe600` | Warning active states |
-| Error disabled background | `system.color.bg.critical.softer` | `colors.cinnamon100` | Disabled error button |
-| Error default background | `system.color.bg.critical.default` | `colors.cinnamon500` | Error message background |
-| Error hover background | `system.color.bg.critical.strong` | `colors.cinnamon600` | Delete button hover |
-| Success surface background | `system.color.bg.positive.softer` | `colors.greenApple100` | Cards showing success status |
-| Success default background | `system.color.bg.positive.default` | `colors.greenApple400` | Disabled success buttons |
-| Success hover background | `system.color.bg.positive.strong` | `colors.greenApple500` | Success button hover |
-| Success active background | `system.color.bg.positive.stronger` | `colors.greenApple600` | Success button active |
-| Muted background (subtle) | `system.color.bg.muted.softer` | `colors.licorice100` | Light containers |
-| Muted background (soft) | `system.color.bg.muted.soft` | `colors.licorice200` | Form backgrounds |
-| Muted background (default) | `system.color.bg.muted.default` | `colors.licorice300` | Input fields, inactive elements |
-| Muted strong background | `system.color.bg.muted.strong` | `colors.licorice500` | Switch toggles, loading indicators |
-| Disabled input background | `system.color.bg.alt.softer` | `colors.soap100`
`inputColors.disabled.background` | Disabled text input fields |
-| Alt page background | `system.color.bg.alt.soft` | `colors.soap200` | Dashboard sections |
-| Secondary surface background | `system.color.bg.alt.default` | `colors.soap300`
`commonColors.backgroundAlt` | Card hover background |
-| Secondary hover background | `system.color.bg.alt.strong` | `colors.soap400`
`commonColors.hoverBackground` | Hover state for modals |
-| Secondary active background | `system.color.bg.alt.stronger` | `colors.soap500` | Clicked state for surfaces |
-| Contrast background (default) | `system.color.bg.contrast.default` | `colors.blackPepper400` | Tooltip background |
-| Contrast background (strong) | `system.color.bg.contrast.strong` | `colors.blackPepper500` | High-contrast text container background |
-| **Foreground Colors (text and icons)** | **System Token** | **Old Token / React tokens** | **Example Usage** |
-| Body foreground | `system.color.fg.default` | `colors.blackPepper300`
`typeColors.body`
`typeColors.label`
`inputColors.text`
| Paragraphs, regular content |
-| Headings | `system.color.fg.strong` | `colors.blackPepper400`
`typeColors.heading` | Section and card headings |
-| Display titles | `system.color.fg.stronger` | `colors.blackPepper500` | Hero titles, large headings |
-| Link foreground | `system.color.fg.primary.default` | `colors.blueberry400`
`iconColors.active`
`statusColors.active`
`typeColors.link`
`typeColors.selectHighlight` | Anchor links |
-| Link foreground hover | `system.color.fg.primary.strong` | `colors.blueberry500` | Hover state for links |
-| Error foreground | `system.color.fg.critical.default` | `colors.cinnamon500`
`inputColors.error.icon`
`statusColors.error` | Error messages |
-| Inverse (white) foreground | `system.color.fg.inverse` | `colors.frenchVanilla100`
`typeColors.inverse`
`typeColors.selectHighlightInverse`
`iconColors.inverse` | Text on dark backgrounds |
-| Disabled foreground | `system.color.fg.disabled` | `colors.licorice100`
`inputColors.disabled.text`
`inputColors.disabled.icon`
`iconColors.disabled` | Disabled buttons and form inputs |
-| Muted foreground (soft) | `system.color.fg.muted.soft` | `colors.licorice200`
`iconColors.standard`
`inputColors.icon`
`typeColors.hint` | Tab labels, hint text |
-| Muted foreground (default) | `system.color.fg.muted.default` | `colors.licorice300`
`inputColors.placeholder` | Subtitle or secondary text |
-| Muted foreground (strong) | `system.color.fg.muted.strong` | `colors.licorice400` | Hover state for muted elements |
-| Muted foreground (stronger) | `system.color.fg.muted.stronger` | `colors.licorice500`
`iconColors.hover`
`inputColors.iconHover` | Active muted tabs text |
-| **Border Colors** | **System Token** | **Old Token / React tokens** | **Example Usage** |
-| Contrast border | `system.color.border.contrast.default` | `colors.blackPepper400` | Card outline, divider on light surfaces |
-| Strong contrast border | `system.color.border.contrast.strong` | `colors.blackPepper500` | High-contrast outlines or focus states |
-| Primary active input border | `system.color.border.primary.default` | `colors.blueberry400`
`commonColors.focusOutline`
`inputColors.focusBorder` | Active input fields |
-| Warning border (inner) | `system.color.border.caution.default` | `colors.cantaloupe400`
`inputColors.alert.border`
`statusColors.warning` | Alert field inner border |
-| Warning border (outer) | `system.color.border.caution.strong` | `colors.cantaloupe600` | Alert field box shadow |
-| Error border | `system.color.border.critical.default` | `colors.cinnamon500`
`inputColors.error.border`
`statusColors.error` | Form field with error |
-| Inverse surface border | `system.color.border.inverse` | `colors.frenchVanilla100` | Checkbox/radio on dark background |
-| Disabled input border | `system.color.border.input.disabled` | `colors.licorice100` | Non-editable input fields |
-| Default input border | `system.color.border.input.default` | `colors.licorice200`
`inputColors.border` | Normal input field border |
-| Hover input border | `system.color.border.input.strong` | `colors.licorice500`
`inputColors.disabled.border` | Input field on hover |
-| Inverse input border | `system.color.border.input.inverse` | `colors.soap300` | Inverse theme inputs |
-| Divider/separator border | `system.color.border.divider` | `colors.soap400`
`commonColors.divider` | Table rows, content separators |
-| Container border (card/table edge) | `system.color.border.container` | `colors.soap500` | Card edge or section container border |
-| **Static Colors** | **System Token** | **Old Token / React tokens** | **Example Usage** |
-| White | `system.color.static.white` | | Always white regardless of theme |
-| Black | `system.color.static.black` | | Always black regardless of theme |
-| Transparent | `system.color.static.transparent` | | Invisible backgrounds |
+| Use Case | System Token (v4) | Old Token / React tokens | Example Usage |
+| -------------------------------------- | :-------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------: | ---------------------------------------- |
+| **Background Colors** | | | |
+| Main page background | `system.color.surface.default` | `colors.frenchVanilla100`
`inputColors.background`
`commonColors.background` | Page layout base background |
+| Disabled elements | `system.color.brand.surface.primary.default` | `colors.blueberry200` | Disabled primary buttons |
+| Brand default background | `system.color.brand.accent.primary.default` | `colors.blueberry400`
`commonColors.focusBackground`
`inputColors.selectionControlFill` | Brand banners, primary button background |
+| Brand hover background | `system.color.brand.accent.primary.default` | `colors.blueberry500` | Primary button hover |
+| Brand active background | `system.color.brand.accent.primary.default` | `colors.blueberry600` | Primary button active |
+| Warning subtle background | `system.color.brand.surface.caution.strong` | `colors.cantaloupe100` | Soft warning banners |
+| Warning default background | `system.color.brand.accent.caution.default` | `colors.cantaloupe400` | Toast notifications |
+| Warning hover background | `system.color.brand.accent.caution.default` | `colors.cantaloupe500` | Warning hover states |
+| Warning active background | `system.color.brand.accent.caution.default` | `colors.cantaloupe600` | Warning active states |
+| Error disabled background | `system.color.brand.surface.critical.strong` | `colors.cinnamon100` | Disabled error button |
+| Error default background | `system.color.brand.accent.critical` | `colors.cinnamon500` | Error message background |
+| Error hover background | `system.color.surface.danger.default` | `colors.cinnamon600` | Delete button hover |
+| Success surface background | `system.color.brand.surface.positive.default` | `colors.greenApple100` | Cards showing success status |
+| Success default background | `system.color.brand.accent.positive.default` | `colors.greenApple400` | Disabled success buttons |
+| Success hover background | `system.color.brand.accent.positive.default` | `colors.greenApple500` | Success button hover |
+| Success active background | `system.color.brand.accent.positive.default` | `colors.greenApple600` | Success button active |
+| Muted background (subtle) | `system.color.accent.muted.soft` | `colors.licorice100` | Light containers |
+| Muted background (soft) | `system.color.accent.muted.soft` | `colors.licorice200` | Form backgrounds |
+| Muted background (default) | `system.color.accent.muted.default` | `colors.licorice300` | Input fields, inactive elements |
+| Muted strong background | `system.color.accent.muted.default` | `colors.licorice500` | Switch toggles, loading indicators |
+| Disabled input background | `system.color.surface.raised` | `colors.soap100`
`inputColors.disabled.background` | Disabled text input fields |
+| Alt page background | `system.color.surface.alt.default` | `colors.soap200` | Dashboard sections |
+| Secondary surface background | `system.color.surface.alt.default` | `colors.soap300`
`commonColors.backgroundAlt` | Card hover background |
+| Secondary hover background | `system.color.surface.alt.default` | `colors.soap400`
`commonColors.hoverBackground` | Hover state for modals |
+| Secondary active background | `system.color.surface.alt.default` | `colors.soap500` | Clicked state for surfaces |
+| Contrast background (default) | `system.color.surface.contrast.default` | `colors.blackPepper400` | Tooltip background |
+| Contrast background (strong) | `system.color.surface.contrast.strong` | `colors.blackPepper500` | High-contrast text container background |
+| **Foreground Colors (text and icons)** | **System Token (v4)** | **Old Token / React tokens** | **Example Usage** |
+| Body foreground | `system.color.fg.default` | `colors.blackPepper300`
`typeColors.body`
`typeColors.label`
`inputColors.text`
| Paragraphs, regular content |
+| Headings | `system.color.fg.strong` | `colors.blackPepper400`
`typeColors.heading` | Section and card headings |
+| Display titles | `system.color.fg.stronger` | `colors.blackPepper500` | Hero titles, large headings |
+| Link foreground | `system.color.brand.fg.primary.default` | `colors.blueberry400`
`iconColors.active`
`statusColors.active`
`typeColors.link`
`typeColors.selectHighlight` | Anchor links |
+| Link foreground hover | `system.color.brand.fg.primary.strong` | `colors.blueberry500` | Hover state for links |
+| Error foreground | `system.color.brand.fg.critical.default` | `colors.cinnamon500`
`inputColors.error.icon`
`statusColors.error` | Error messages |
+| Inverse (white) foreground | `system.color.fg.inverse` | `colors.frenchVanilla100`
`typeColors.inverse`
`typeColors.selectHighlightInverse`
`iconColors.inverse` | Text on dark backgrounds |
+| Disabled foreground | `system.color.fg.disabled` | `colors.licorice100`
`inputColors.disabled.text`
`inputColors.disabled.icon`
`iconColors.disabled` | Disabled buttons and form inputs |
+| Muted foreground (soft) | `system.color.fg.muted.default` | `colors.licorice200`
`iconColors.standard`
`inputColors.icon`
`typeColors.hint` | Tab labels, hint text |
+| Muted foreground (default) | `system.color.fg.muted.default` | `colors.licorice300`
`inputColors.placeholder` | Subtitle or secondary text |
+| Muted foreground (strong) | `system.color.fg.muted.strong` | `colors.licorice400` | Hover state for muted elements |
+| Muted foreground (stronger) | `system.color.fg.muted.strong` | `colors.licorice500`
`iconColors.hover`
`inputColors.iconHover` | Active muted tabs text |
+| **Border Colors** | **System Token (v4)** | **Old Token / React tokens** | **Example Usage** |
+| Contrast border | `system.color.border.contrast.default` | `colors.blackPepper400` | Card outline, divider on light surfaces |
+| Strong contrast border | `system.color.border.contrast.strong` | `colors.blackPepper500` | High-contrast outlines or focus states |
+| Primary active input border | `system.color.border.primary.default` | `colors.blueberry400`
`commonColors.focusOutline`
`inputColors.focusBorder` | Active input fields |
+| Warning border (inner) | `system.color.brand.focus.caution.inner` | `colors.cantaloupe400`
`inputColors.alert.border`
`statusColors.warning` | Alert field inner border |
+| Warning border (outer) | `system.color.brand.focus.caution.outer` | `colors.cantaloupe600` | Alert field box shadow |
+| Error border | `system.color.border.critical.default` | `colors.cinnamon500`
`inputColors.error.border`
`statusColors.error` | Form field with error |
+| Inverse surface border | `system.color.border.inverse` | `colors.frenchVanilla100` | Checkbox/radio on dark background |
+| Disabled input border | `system.color.border.input.default` | `colors.licorice100` | Non-editable input fields |
+| Default input border | `system.color.border.input.default` | `colors.licorice200`
`inputColors.border` | Normal input field border |
+| Hover input border | `system.color.border.input.hover` | `colors.licorice500`
`inputColors.disabled.border` | Input field on hover |
+| Inverse input border | `system.color.border.input.inverse` | `colors.soap300` | Inverse theme inputs |
+| Divider/separator border | `system.color.border.default` | `colors.soap400`
`commonColors.divider` | Table rows, content separators |
+| Container border (card/table edge) | `system.color.border.strong` | `colors.soap500` | Card edge or section container border |
+| **Static Colors** | **System Token (v4)** | **Old Token / React tokens** | **Example Usage** |
+| White | `system.color.static.white` | | Always white regardless of theme |
+| Black | `system.color.static.black` | | Always black regardless of theme |
+| Transparent | `system.color.static.transparent` | | Invisible backgrounds |
## Migration Examples
@@ -330,23 +332,15 @@ themeable, understandable, and consistent.**
```javascript
// Old
import {colors} from '@workday/canvas-kit-react/tokens';
-backgroundColor: colors.frenchVanilla100;
-// New (Direct mapping)
-import {base} from '@workday/canvas-tokens-web';
-backgroundColor: cssVar(base.neutral0);
+backgroundColor: colors.frenchVanilla100;
```
-**Example 3: Brand Color Migration**
-
-```javascript
-// Old
-import {theme} from '@emotion/react';
-backgroundColor: theme.canvas.palette.primary.main;
-
+```js
// New
-import {brand} from '@workday/canvas-tokens-web';
-backgroundColor: cssVar(brand.primary.base);
+import {base} from '@workday/canvas-tokens-web';
+
+backgroundColor: cssVar(base.neutral0);
```
**Example 2: System Color Migration**
@@ -360,11 +354,27 @@ const styles = createStyles({
color: colors.blackPepper300,
});
-// New - Using semantic system tokens
+// New - Using v4 semantic system tokens (system.color.*)
import {system} from '@workday/canvas-tokens-web';
const styles = createStyles({
- backgroundColor: system.color.bg.default,
- borderColor: system.color.border.container,
- color: system.color.text.default,
+ backgroundColor: system.color.surface.default,
+ borderColor: system.color.border.strong,
+ color: system.color.fg.default,
});
```
+
+**Example 3: Brand Color Migration**
+
+```javascript
+// Old
+import {theme} from '@emotion/react';
+
+backgroundColor: theme.canvas.palette.primary.main;
+```
+
+```js
+// New (v4)
+import {brand} from '@workday/canvas-tokens-web';
+
+backgroundColor: cssVar(brand.primary600);
+```
diff --git a/modules/docs/mdx/tokens/TokenMigrationMappingSystem.mdx b/modules/docs/mdx/tokens/TokenMigrationMappingSystem.mdx
index 18df40506e..c5b50fe226 100644
--- a/modules/docs/mdx/tokens/TokenMigrationMappingSystem.mdx
+++ b/modules/docs/mdx/tokens/TokenMigrationMappingSystem.mdx
@@ -1,4 +1,5 @@
import {Meta} from '@storybook/blocks';
+
import {StorybookInformationHighlight} from './StorybookInformationHighlight';
@@ -7,18 +8,22 @@ import {StorybookInformationHighlight} from './StorybookInformationHighlight';
## Space
-| Old Token | New Token |
-| ------------ | ------------------- |
-| `space.zero` | `system.space.zero` |
-| `space.xxxs` | `system.space.x1` |
-| `space.xxs` | `system.space.x2` |
-| `space.xs` | `system.space.x3` |
-| `space.s` | `system.space.x4` |
-| `space.m` | `system.space.x6` |
-| `space.l` | `system.space.x8` |
-| `space.xl` | `system.space.x10` |
-| `space.xxl` | `system.space.x16` |
-| `space.xxxl` | `system.space.x20` |
+- Use `system.size.*` tokens for width or height properties.
+- Use `system.gap.*` tokens for outer spacing, like `gap` or `margin` properties.
+- Use `system.padding.*` tokens for inner spacing, like `padding` properties.
+
+| Old Token | v2/v3 Token | v4 Token :: Size | v4 Token :: Gap | v4 Token :: Padding | Raw Value |
+| ------------ | ------------------- | :----------------: | :---------------: | :-------------------: | --------- |
+| `space.zero` | `system.space.zero` | `base.size0` | `system.gap.none` | `system.padding.none` | `0` |
+| `space.xxxs` | `system.space.x1` | `base.size50` | `system.gap.xs` | `system.padding.xxs` | `4px` |
+| `space.xxs` | `system.space.x2` | `base.size100` | `system.gap.sm` | `system.padding.xs` | `8px` |
+| `space.xs` | `system.space.x3` | `base.size150` | - | `system.padding.sm` | `12px` |
+| `space.s` | `system.space.x4` | `system.size.xxxs` | `system.gap.md` | `system.padding.md` | `16px` |
+| `space.m` | `system.space.x6` | `system.size.xs` | `system.gap.lg` | `system.padding.xl` | `24px` |
+| `space.l` | `system.space.x8` | `system.size.sm` | `system.gap.xl` | `system.padding.xxl` | `32px` |
+| `space.xl` | `system.space.x10` | `system.size.md` | - | - | `40px` |
+| `space.xxl` | `system.space.x16` | `system.size.xxl` | `system.gap.xxl` | - | `64px` |
+| `space.xxxl` | `system.space.x20` | `base.size1000` | - | - | `80px` |
**Example migration**
@@ -33,20 +38,20 @@ const styles = createStyles({
// New
import {system} from '@workday/canvas-tokens-web';
const styles = createStyles({
- padding: system.space.x8,
- margin: system.space.x6,
+ padding: system.padding.xxl,
+ margin: system.gap.lg,
});
```
## Shape (Border Radius) Token Migration
-| Old Token | New Token |
-| --------------------- | -------------------- |
-| `borderRadius.zero` | `system.shape.zero` |
-| `borderRadius.s` | `system.shape.half` |
-| `borderRadius.m` | `system.shape.x1` |
-| `borderRadius.l` | `system.shape.x2` |
-| `borderRadius.circle` | `system.shape.round` |
+| Old Token | v2/v3 Token | v4 Token | Raw Value |
+| --------------------- | -------------------- | ------------------- | --------- |
+| `borderRadius.zero` | `system.shape.zero` | `system.shape.none` | `0` |
+| `borderRadius.s` | `system.shape.half` | `px2rem(2)` | `2px` |
+| `borderRadius.m` | `system.shape.x1` | `system.shape.sm` | `4px` |
+| `borderRadius.l` | `system.shape.x2` | `system.shape.md` | `8px` |
+| `borderRadius.circle` | `system.shape.round` | `system.shape.full` | `1000px` |
**Example migration**
@@ -55,7 +60,7 @@ const styles = createStyles({
borderRadius: borderRadius.m;
// New
-borderRadius: system.shape.x1;
+borderRadius: system.shape.sm;
```
## Typography Token Migration
@@ -69,28 +74,28 @@ borderRadius: system.shape.x1;
### Font Size
-| Old Token | New Token |
-| ------------------------------- | -------------------------------- |
-| `type.properties.fontSizes[10]` | `system.fontSize.subtext.small` |
-| `type.properties.fontSizes[12]` | `system.fontSize.subtext.medium` |
-| `type.properties.fontSizes[14]` | `system.fontSize.subtext.large` |
-| `type.properties.fontSizes[16]` | `system.fontSize.body.small` |
-| `type.properties.fontSizes[18]` | `system.fontSize.body.medium` |
-| `type.properties.fontSizes[20]` | `system.fontSize.body.large` |
-| `type.properties.fontSizes[24]` | `system.fontSize.heading.small` |
-| `type.properties.fontSizes[28]` | `system.fontSize.heading.medium` |
-| `type.properties.fontSizes[32]` | `system.fontSize.heading.large` |
-| `type.properties.fontSizes[40]` | `system.fontSize.title.small` |
-| `type.properties.fontSizes[48]` | `system.fontSize.title.medium` |
-| `type.properties.fontSizes[56]` | `system.fontSize.title.large` |
+| Old Token | v2/v3 Token | v4 Token |
+| ------------------------------- | -------------------------------- | ---------------------------- |
+| `type.properties.fontSizes[10]` | `system.fontSize.subtext.small` | `system.fontSize.subtext.sm` |
+| `type.properties.fontSizes[12]` | `system.fontSize.subtext.medium` | `system.fontSize.subtext.md` |
+| `type.properties.fontSizes[14]` | `system.fontSize.subtext.large` | `system.fontSize.subtext.lg` |
+| `type.properties.fontSizes[16]` | `system.fontSize.body.small` | `system.fontSize.body.sm` |
+| `type.properties.fontSizes[18]` | `system.fontSize.body.medium` | `system.fontSize.body.md` |
+| `type.properties.fontSizes[20]` | `system.fontSize.body.large` | `system.fontSize.body.lg` |
+| `type.properties.fontSizes[24]` | `system.fontSize.heading.small` | `system.fontSize.heading.sm` |
+| `type.properties.fontSizes[28]` | `system.fontSize.heading.medium` | `system.fontSize.heading.md` |
+| `type.properties.fontSizes[32]` | `system.fontSize.heading.large` | `system.fontSize.heading.lg` |
+| `type.properties.fontSizes[40]` | `system.fontSize.title.small` | `system.fontSize.title.sm` |
+| `type.properties.fontSizes[48]` | `system.fontSize.title.medium` | `system.fontSize.title.md` |
+| `type.properties.fontSizes[56]` | `system.fontSize.title.large` | `system.fontSize.title.lg` |
### Font Weight Mappings
-| Old Token | New Token |
-| ------------------------------------- | --------------------------- |
-| `type.properties.fontWeights.regular` | `system.fontWeight.regular` |
-| `type.properties.fontWeights.medium` | `system.fontWeight.medium` |
-| `type.properties.fontWeights.bold` | `system.fontWeight.bold` |
+| Old Token | New Token |
+| ------------------------------------- | -------------------------- |
+| `type.properties.fontWeights.regular` | `system.fontWeight.normal` |
+| `type.properties.fontWeights.medium` | `system.fontWeight.medium` |
+| `type.properties.fontWeights.bold` | `system.fontWeight.bold` |
### Type Levels (Recommended)
@@ -103,18 +108,18 @@ import { type } from '@workday/canvas-kit-react/tokens';
// New
import { system } from '@workday/canvas-tokens-web';
-...system.type.body.medium
+...system.type.body.md
```
### Type Variants → Text Colors
Type variants are replaced with semantic text color tokens:
-| Old Token | New Token |
-| ---------------------- | ------------------------------------ |
-| `type.variant.error` | `system.color.text.critical.default` |
-| `type.variant.hint` | `system.color.text.hint` |
-| `type.variant.inverse` | `system.color.text.inverse` |
+| Old Token | v2/v3 Token | v4 Token |
+| ---------------------- | ------------------------------------ | ---------------------------------- |
+| `type.variant.error` | `system.color.text.critical.default` | `system.color.fg.critical.default` |
+| `type.variant.hint` | `system.color.text.hint` | `system.color.fg.muted.default` |
+| `type.variant.inverse` | `system.color.text.inverse` | `system.color.fg.inverse` |
### Depth (Shadow) Token Migration
@@ -135,155 +140,3 @@ const styles = createStyles({
boxShadow: system.depth[1],
});
```
-
-## Complete Migration Examples
-
-### Example 1: Card Component Migration
-
-#### Before (Old Tokens)
-
-```javascript
-import {colors, space, borderRadius, type, depth} from '@workday/canvas-kit-react/tokens';
-import {createStyles} from '@workday/canvas-kit-styling';
-
-const cardStyles = createStyles({
- padding: space.l,
- backgroundColor: colors.frenchVanilla100,
- borderColor: colors.soap500,
- borderRadius: borderRadius.m,
- color: colors.blackPepper300,
- depth: 1,
- ...type.levels.body.medium,
-});
-
-const headerStyles = createStyles({
- color: colors.blackPepper500,
- marginBottom: space.s,
- ...type.levels.heading.small,
-});
-
-const errorTextStyles = createStyles({
- color: colors.cinnamon500,
- ...type.levels.subtext.large,
-});
-```
-
-#### After (New Tokens - Semantic System Approach)
-
-```javascript
-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,
- border: `solid ${px2rem(1)}`,
- borderColor: system.color.border.container,
- borderRadius: system.shape.x1,
- color: system.color.text.default,
- boxShadow: system.depth[1],
- ...system.type.body.medium,
-});
-
-const headerStyles = createStyles({
- color: system.color.text.default,
- marginBottom: system.space.x4,
- ...system.type.heading.small,
-});
-
-const errorTextStyles = createStyles({
- color: system.color.text.critical.default,
- ...system.type.subtext.large,
-});
-```
-
-### Example 2: Form Input Migration
-
-#### Before (Old Tokens)
-
-```javascript
-import {colors, space, borderRadius} from '@workday/canvas-kit-react/tokens';
-
-const inputStyles = createStyles({
- padding: `${space.xs} ${space.s}`,
- backgroundColor: colors.frenchVanilla100,
- borderColor: colors.soap400,
- borderRadius: borderRadius.s,
- color: colors.blackPepper400,
- '&:focus': {
- borderColor: colors.blueberry400,
- backgroundColor: colors.frenchVanilla100,
- },
- '&.error': {
- borderColor: colors.cinnamon500,
- backgroundColor: colors.cinnamon100,
- },
- '&:disabled': {
- backgroundColor: colors.soap200,
- color: colors.soap600,
- },
-});
-```
-
-#### After (New Tokens - System Approach)
-
-```javascript
-import {system} from '@workday/canvas-tokens-web';
-
-const inputStyles = createStyles({
- padding: `${system.space.x3} ${system.space.x4}`,
- backgroundColor: system.color.bg.default,
- borderColor: system.color.border.default,
- borderRadius: system.shape.half,
- color: system.color.text.default,
- '&:focus': {
- borderColor: system.color.border.contrast,
- backgroundColor: system.color.bg.default,
- },
- '&.error': {
- borderColor: system.color.border.critical.default,
- backgroundColor: system.color.bg.critical.subtle,
- },
- '&:disabled': {
- backgroundColor: system.color.bg.disabled,
- color: system.color.text.disabled,
- },
-});
-```
-
-### Example 3: Button Migration with Brand Colors
-
-#### Before (Old Tokens)
-
-```javascript
-import {colors, space, borderRadius} from '@workday/canvas-kit-react/tokens';
-import {theme} from '@emotion/react';
-
-const primaryButtonStyles = createStyles({
- padding: `${space.xs} ${space.m}`,
- backgroundColor: theme.canvas.palette.primary.main,
- borderColor: theme.canvas.palette.primary.main,
- borderRadius: borderRadius.m,
- color: theme.canvas.palette.primary.contrast,
- '&:hover': {
- backgroundColor: theme.canvas.palette.primary.dark,
- },
-});
-```
-
-#### After (New Tokens - Brand + System)
-
-```javascript
-import {system, brand} 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,
- '&:hover': {
- backgroundColor: brand.primary.dark,
- },
-});
-```
diff --git a/modules/docs/mdx/tokens/TokenMigrationOverview.mdx b/modules/docs/mdx/tokens/TokenMigrationOverview.mdx
index 72630055a6..6822c350ac 100644
--- a/modules/docs/mdx/tokens/TokenMigrationOverview.mdx
+++ b/modules/docs/mdx/tokens/TokenMigrationOverview.mdx
@@ -6,20 +6,15 @@ import {StorybookInformationHighlight} from './StorybookInformationHighlight';
-# Canvas Kit Token Migration Guide: Moving to `@workday/canvas-tokens-web@3.0.0`
-
-
+# Canvas Kit Token Migration Guide: Moving to `@workday/canvas-tokens-web@4.0.0`
Canvas Kit v10+ introduces a new token system that replaces the old JavaScript-based tokens from
`@workday/canvas-kit-react/tokens` with CSS variables from `@workday/canvas-tokens-web`. Canvas Kit
-is using tokens from `@workday/canvas-tokens-web` v3 that introduced a new color palette with more
-clear names (like `red.600`, `blue100`) instead of the previous "fruity" palette (like `watermelon`,
-`blueberry`, etc).
+is using tokens from `@workday/canvas-tokens-web` v4 that introduced significant updates to align
+with our Design Refresh, providing enhanced scalability, better product support, and a more
+comprehensive token system. This release focuses on improving the color system with extended alpha
+scales, updating brand tokens to use numerical naming conventions, and introducing new surface,
+focus, accent, and semantic tokens.
## Why Migrate?
@@ -38,31 +33,6 @@ clear names (like `red.600`, `blue100`) instead of the previous "fruity" palette
linkText="Learn more about the Canvas Kit MCP"
/>
-We provide a **LLM migration mapping file** (`llm-token-migration.txt`) specifically designed for
-use with LLM-based code assistants (such as [Cursor](https://www.cursor.so/) or similar tools). This
-file is not intended for direct human reference or team documentation, but rather as structured
-input for LLMs to automate and assist with your token migration process.
-
-> Important: LLMs can make mistakes. Please review changes to be sure they are correct using our
-> docs and upgrade guides. The LLM migration file is regularly updated to reflect the latest token
-> mappings and best practices. For more details, see other sections of this migration guide.
-
-This file contains a comprehensive mapping of old Canvas Kit token usages to their new equivalents
-in `@workday/canvas-tokens-web`, along with migration tips and examples and formatted for optimal
-LLM consumption.
-
-**How to use:**
-
-- **View raw file**: Open the file in a new tab to see the complete migration mapping
-- **Download as txt**: 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
-
-
-
## Core Principles
### Token Hierarchy
@@ -86,15 +56,11 @@ import {space} from '@workday/canvas-kit-react/tokens';
// padding: '1rem'
const styles = {padding: space.s};
-// New approach - CSS variables with var()
-import {system} from '@workday/canvas-tokens-web';
-// padding: 'var(--cnvs-sys-space-x4)'
-const styles = {padding: `var(${system.space.x4})`};
-
// New approach - Using cssVar utility (recommended) and fallback
import {cssVar} from '@workday/canvas-kit-styling';
-// padding: 'var(--cnvs-sys-space-x4, 1rem)'
-const styles = {padding: cssVar(system.space.x4, '1rem')};
+import {system} from '@workday/canvas-tokens-web';
+// padding: 'var(--cnvs-sys-padding-md, 1rem)'
+const styles = {padding: cssVar(system.padding.md, '1rem')};
```
### Styling Utilities
@@ -119,7 +85,7 @@ Use system tokens over base tokens whenever possible for better theming support:
```javascript
// Good - Semantic and themeable
-backgroundColor: system.color.bg.default;
+backgroundColor: system.color.surface.default;
// Avoid - Hard-coded base value
backgroundColor: base.neutral0;
@@ -131,10 +97,10 @@ Instead of mixing individual type properties, use complete type level tokens:
```javascript
// Good - Consistent type styling
-...system.type.body.medium
+...system.type.body.md
// Avoid - Mixing individual properties
-fontSize: system.fontSize.body.medium,
+fontSize: system.fontSize.body.md,
fontWeight: system.fontWeight.regular,
lineHeight: '1.5'
```
@@ -146,12 +112,12 @@ Always use `createStyles` and `cssVar` for proper CSS variable handling:
```javascript
// Good - Proper CSS variable wrapping
const styles = createStyles({
- padding: system.space.x4,
+ padding: system.padding.md,
});
// Avoid - Manual CSS variable handling
const styles = {
- padding: `var(${system.space.x4})`,
+ padding: `var(${system.padding.md})`,
};
```
@@ -161,9 +127,10 @@ Use `px2rem` for pixel-based values to maintain consistency:
```javascript
import {px2rem} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
const styles = createStyles({
border: `solid ${px2rem(1)}`,
- borderColor: system.color.border.container,
+ borderColor: system.color.border.strong,
});
```