@workday/canvas-kit-docs 15.0.0-alpha.1303-next.0 → 15.0.0

package/dist/mdx/tokens/TokenMigrationMappingSystem.mdx

@@ -5,18 +5,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**
 
@@ -31,20 +35,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**
 
@@ -53,7 +57,7 @@ const styles = createStyles({
 borderRadius: borderRadius.m;
 
 // New
-borderRadius: system.shape.x1;
+borderRadius: system.shape.sm;
 ```
 
 ## Typography Token Migration
@@ -67,28 +71,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)
 
@@ -101,18 +105,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
 
@@ -132,156 +136,4 @@ const styles = createStyles({
 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,
-  },
-});
 ```

package/dist/mdx/tokens/TokenMigrationOverview.mdx

@@ -1,14 +1,17 @@
-import {StorybookStatusIndicator, DownloadLLMFile} from '@workday/canvas-kit-docs';
+import {DownloadLLMFile, StorybookStatusIndicator} from '@workday/canvas-kit-docs';
+
 import {StorybookInformationHighlight} from './StorybookInformationHighlight';
 
 
-# Canvas Kit Token Migration Guide: Moving to `@workday/canvas-tokens-web`
+# 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?
 
@@ -20,29 +23,11 @@ clear names (like `red.600`, `blue100`) instead of the previous "fruity" palette
 
 ## LLM Assisted Migration <StorybookStatusIndicator type="ai" />
 
-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
-
-<DownloadLLMFile
-  rawFileLink="https://raw.githubusercontent.com/Workday/canvas-kit/master/modules/docs/llm-txt/llm-token-migration-14.txt"
-  filename="llm-token-migration-14.0.0.txt"
+<StorybookInformationHighlight
+  title="Note: Looking for an easier path to migrate?"
+  description="We recommend using the Canvas Kit MCP"
+  link="/?path=/docs/ai-for-llms-mcp-docs--docs"
+  linkText="Learn more about the Canvas Kit MCP"
 />
 
 ## Core Principles
@@ -68,15 +53,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
@@ -101,7 +82,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;
@@ -113,10 +94,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'
 ```
@@ -128,12 +109,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})`,
 };
 ```
 
@@ -143,9 +124,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,
 });
 ```

package/dist/mdx/welcome.mdx

@@ -1,36 +1,34 @@
-import Readme from '../../../README.md';
-import Markdown from '../../../utils/storybook/Markdown.tsx';
-import { WelcomePage } from './welcomePage';
-import { InstallBlock } from './installBlock';
-import { version } from '../../../lerna.json';
+import {version} from '../../../lerna.json';
+import {InstallBlock} from './installBlock';
+import {WelcomePage} from './welcomePage';
 
 
 <WelcomePage />
 
 ### Canvas Provider
 
-If you use Emotion for styling your components, the `<CanvasProvider>` ensures your styles will merge as expected. Note:
-Custom use of `<CacheProvider>` provided by Emotion is not supported. `@workday/canvas-kit-styling`
-owns the creating of the cache reference. This ensures both static styling and Emotion’s dynamic
-styling solutions work together. In most cases you'll want to wrap your application at the root
-level in `<CanvasProvider>`.
+If you use Emotion for styling your components, the `<CanvasProvider>` ensures your styles will
+merge as expected. Note: Custom use of `<CacheProvider>` provided by Emotion is not supported.
+`@workday/canvas-kit-styling` owns the creating of the cache reference. This ensures both static
+styling and Emotion’s dynamic styling solutions work together. In most cases you'll want to wrap
+your application at the root level in `<CanvasProvider>`.
 
 ```tsx
 import * as React from 'react';
-import {
-  CanvasProvider,
-} from '@workday/canvas-kit-react/common';
+
+import {CanvasProvider} from '@workday/canvas-kit-react/common';
 // Ensure CSS variables are defined. You Can also do this at the root index.css
 import '@workday/canvas-tokens-web/css/base/_variables.css';
 import '@workday/canvas-tokens-web/css/brand/_variables.css';
+import '@workday/canvas-tokens-web/css/component/_variables.css';
 import '@workday/canvas-tokens-web/css/system/_variables.css';
 
 export const App = () => {
   return (
     <CanvasProvider>
-        <main>
-          <p>Get Started With Canvas Kit</p>
-        </main>
+      <main>
+        <p>Get Started With Canvas Kit</p>
+      </main>
     </CanvasProvider>
   );
 };

package/lib/DescriptionTooltip.tsx

@@ -1,12 +1,17 @@
-import styled from '@emotion/styled';
-import {Tooltip} from '@workday/canvas-kit-react/tooltip';
-import {colors} from '@workday/canvas-kit-react/tokens';
+import {Tooltip, TooltipProps} from '@workday/canvas-kit-react/tooltip';
+import {cssVar, px2rem} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
 
-export const DescriptionTooltip = styled(Tooltip)({
-  ':before': {
-    borderWidth: 1,
-    borderStyle: 'solid',
-    borderColor: colors.blackPepper500,
-    backgroundColor: 'rgba(255,255,255,.85)',
-  },
-});
+export const DescriptionTooltip = (props: TooltipProps) => (
+  <Tooltip
+    cs={{
+      ':before': {
+        borderWidth: px2rem(1),
+        borderStyle: 'solid',
+        borderColor: system.color.border.contrast.default,
+        backgroundColor: `oklch(from ${cssVar(system.color.surface.default)} / ${system.opacity.contrast})`,
+      },
+    }}
+    {...props}
+  />
+);

package/lib/DownloadLLMFile.tsx

@@ -1,8 +1,8 @@
-import {Card} from '@workday/canvas-kit-react/card';
 import {ExternalHyperlink, SecondaryButton} from '@workday/canvas-kit-react/button';
-import {downloadIcon, fileIcon} from '@workday/canvas-system-icons-web';
-import {SystemIcon} from '@workday/canvas-kit-react';
-import {createStencil} from '@workday/canvas-kit-styling';
+import {Card} from '@workday/canvas-kit-react/card';
+import {SystemIcon} from '@workday/canvas-kit-react/icon';
+import {createStencil, cssVar, px2rem} from '@workday/canvas-kit-styling';
+import {documentIcon, downloadIcon} from '@workday/canvas-system-icons-web';
 import {system} from '@workday/canvas-tokens-web';
 
 type DownloadLLMFileProps = {
@@ -12,18 +12,18 @@ type DownloadLLMFileProps = {
 
 const flexBlock = createStencil({
   vars: {
-    gap: system.space.x1,
+    gap: '',
   },
   base: ({gap}) => ({
     display: 'flex',
     alignItems: 'center',
-    gap,
+    gap: cssVar(gap, system.gap.xs),
     code: {
       fontFamily: system.fontFamily.mono,
-      padding: system.space.x1,
-      paddingInline: system.space.x2,
-      backgroundColor: system.color.bg.alt.softer,
-      borderRadius: system.shape.half,
+      padding: system.padding.xxs,
+      paddingInline: system.padding.xs,
+      backgroundColor: system.color.surface.alt.default,
+      borderRadius: px2rem(2),
     },
   }),
 });
@@ -54,10 +54,10 @@ export const DownloadLLMFile = ({rawFileLink, filename}: DownloadLLMFileProps) =
     <Card className="sb-unstyled" cs={{boxShadow: 'none', borderStyle: 'dashed'}}>
       <Card.Body cs={{display: 'grid', gridTemplateColumns: '1fr auto', alignItems: 'center'}}>
         <div {...flexBlock()}>
-          <SystemIcon icon={fileIcon} />
+          <SystemIcon icon={documentIcon} />
           <code>{filename}</code>
         </div>
-        <div {...flexBlock({gap: system.space.x4})}>
+        <div {...flexBlock({gap: system.gap.md})}>
           <ExternalHyperlink href={rawFileLink}>View raw file</ExternalHyperlink>
           <SecondaryButton icon={downloadIcon} size="small" onClick={handleDownload}>
             Download LLM File