@workday/canvas-kit-docs 14.0.0-alpha.1251-next.0 → 14.0.0-alpha.1253-next.0

package/dist/mdx/14.0-UPGRADE-GUIDE.mdx

@@ -4,6 +4,15 @@ This guide contains an overview of the changes in Canvas Kit v14. Please
 [reach out](https://github.com/Workday/canvas-kit/issues/new?labels=bug&template=bug.md) if you have
 any questions.
 
+## Why You Should Upgrade
+
+v14.0 Introduces Workday's new brand direction which includes a new color palette and with it, some
+styling updates to our components.
+
+- For a list of visual changes, please view our v14 visual changes doc [here](https://workday.github.io/canvas-kit/?path=/docs/guides-upgrade-guides-v14-0-visual-changes--docs).
+
+> **Note:** While v14 does not require an upgrade to our v3 tokens, we strongly advise to upgrade to the latest to ensure proper branding.
+
 ## Table of contents
 
 - [Codemod](#codemod)
@@ -13,32 +22,32 @@ any questions.
 - [Theming](#theming)
   - [Canvas Provider](#canvas-provider-)
 - [Component Updates](#component-updates)
-  - [Avatar in Preview](#avatar-in-preview)
-  - [Branding Changes](#branding-changes)
+  - [Avatar (Preview)](#avatar-preview)
+  - [Branding Changes](#branding-changes-)
   - [Buttons](#buttons)
-  - [Card](#card)
+  - [Card](#card-)
   - [Count Badge](#count-badge)
   - [Expandable](#expandable)
-  - [Hyperlink & ExternalHyperlink](#hyperlink-and-externalhyperlink)
+  - [Hyperlink and ExternalHyperlink](#hyperlink-and-external-hyperlink)
   - [Loading Dots](#loading-dots)
-  - [Pill](#pill)
-  - [SearchForm](#search-form)
-  - [Status Indicator (Preview)](#status-indicator-preview)
+  - [Pill (Preview)](#pill-preview)
+  - [Search Form (Labs)](#searchform-)
+  - [Status Indicator (Preview)](#status-indicator-preview-)
 - [Deprecations](#deprecations)
-  - [Avatar in Main](#avatar-in-main)
+  - [Avatar (Main)](#avatar-in-main)
   - [Combobox (Labs)](#combobox-labs)
   - [Radio (Main)](#radio-main)
-  - [SearchForm (Labs)](#search-form-labs)
+  - [Search Form (Labs)](#searchform-labs)
   - [Segmented Control (Main)](#segmented-control-main)
   - [Side Panel (Main)](#side-panel-main)
   - [Tokens](#tokens)
 - [Removals](#removals)
   - [Deprecated Buttons](#deprecated-buttons)
   - [Input Provider](#input-provider)
-  - [Menu (preview)](#menu-preview)
-  - [readyOnlyPillStencil and removeablePillStencil](readyOnlyPillStencil-and-removeablePillStencil)
-  - [Text Area](#text-area)
-  - [Text Input](#text-input)
+  - [Menu (Preview)](#menu-preview)
+  - [readyOnlyPillStencil and removeablePillStencil](#readonlypillstencil-and-removeablepillstencil)
+  - [Text Area (Labs)](#text-area)
+  - [Text Input (Labs)](#text-input)
 - [Troubleshooting](#troubleshooting)
 - [Glossary](#glossary)
   - [Main](#main)
@@ -109,7 +118,7 @@ yarn remove @workday/canvas-kit-codemod
 ## Tokens
 
 Canvas Kit v14 now uses `@workday/canvas-tokens-web` v3, which introduces new color palettes and
-replaces the old "fruity" color names (for example, use `red` instead of `cinnamon`, `blue` instead
+deprecates the old "fruity" color names (for example, use `red` instead of `cinnamon`, `blue` instead
 of `blueberry`, and `green` instead of `greenApple`). We strongly recommend upgrading to
 `@workday/canvas-tokens-web` v3, as using older versions will not match the new brand guidelines or
 color system. Although this dependency upgrade is not required, we've offered migration guides and
@@ -135,8 +144,7 @@ Follow these guides to migrate:
 To better align with the brand refresh, Alert and Warning states are being renamed to Caution for
 better semantics.
 
-This change mostly affects how you pass an error state to our input components. In most cases, our
-inputs components should be used with our `FormField` component to ensure correct accessiblity.
+This change mostly affects how you pass an error state to our input components. In most cases, our input components should be used with our `FormField` component to ensure correct accessibility.
 
 **Before in v13**
 
@@ -162,8 +170,7 @@ inputs components should be used with our `FormField` component to ensure correc
 </FormField>
 ```
 
-If you are using the error type either from our `Common` package or the one exposed from the
-component, the naming as also changed.
+If you are using the error type either from our `Common` package or the one exposed from the component, the naming has also changed.
 
 **Before in v13**
 
@@ -188,7 +195,6 @@ import {TextInput} from '@workday/canvas-kit-react/text-input';
 import {Switch} from '@workday/canvas-kit-react/switch';
 import {TextArea} from '@workday/canvas-kit-react/text-area';
 
-
 someFunction(ErrorType.Caution);
 
 <TextInput error={TextInput.ErrorType.Caution} />
@@ -215,7 +221,11 @@ Canvas Provider has been updated to **remove** default branding colors to ensure
 our CSS variables. Instead of generating a palette and shifting the brightness and darkness with
 `chroma.js`, we use `oklch` to generate the palette colors.
 
-**Before in v13** In v13, the `useTheme` hook would call `createCanvasTheme` which generated a
+Prior to v14, the `CanvasProvider` created a cascade barrier, re definding brand CSS variables under a class, creating a higher specificity. This made it difficult to override brand tokens in certain scenarios. v14 Removes that barrier.
+For more information on what is a cascade barrier, please [view our theming docs here](https://github.com/Workday/canvas-kit/issues). For a mode detailed overview of the changes in v14, please view our [v14 Upgrade Guide](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs#what-is-a-cascade-barrier).
+
+**Before in v13**
+In v13, the `useTheme` hook would call `createCanvasTheme` which generated a
 palette given a `main` color via `chroma.js`.
 
 ```tsx
@@ -251,7 +261,7 @@ different. If you want more control over the colors, we suggest providing the fu
 **Or**
 
 ```tsx
-<CanvasProvider theme={{canvas: {palette: {primary: {main: cssVar(base.blue600)}}}}}>
+<CanvasProvider theme={{canvas: {palette: {primary: {main: base.blue600}}}}}>
   <App />
 </CanvasProvider>
 ```
@@ -273,16 +283,18 @@ The reason for this change is to ensure that the CSS variables properly cascade
 Before in v13, the `CanvasProvider` would add the brand tokens under a class name, creating a higher
 specificity.
 
+For a thorough guide on theming, please view our theming docs [here](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs).
+
 ## Component Updates
 
-### Avatar in Preview
+### Avatar (Preview)
 
 **PR:** [#3430](https://github.com/Workday/canvas-kit/pull/3430)
 
 A new `Avatar` component has been added to the `@workday/canvas-kit-preview-react` package that
 matches our brand refresh.
 
-#### API Changes from the Main Avatar
+#### API Changes from Avatar in Main
 
 - `Avatar` has a `name` prop. This is required to ensure a fallback if a `url` is not provided. The
   `name` prop also determines the initials and the `alt` text for the image if a `url` is provided.
@@ -311,7 +323,7 @@ import { Avatar } from '@workday/canvas-kit-react/avatar';
 
 <Avatar altText="John Doe" size="extraExtraLarge" variant="light" as="div" url={yourImageUrl} />
 
-// For Avatars that where buttons
+// For Avatars that were buttons
 <Avatar altText="John Doe" size="extraExtraLarge" variant="dark" url={yourImageUrl} />
 ```
 
@@ -329,13 +341,15 @@ import { Avatar } from '@workday/canvas-kit-preview-react/avatar';
 ### Branding Changes 💅
 
 Several components have been refactored to reflect our new brand direction. Most of these changes
-revolve around the use of our new brand colors.
+revolve around the use of our new brand colors. For a better guide on what has changed in our v3.0.0
+tokens, please view the Tokens v3.0.0
+[Upgrade Guide](https://workday.github.io/canvas-tokens/?path=/docs/guides-upgrade-guides-v3-overview--docs).
+
+> **Note:** If you want a visual diff of the changes, please view the [Visual Changes](https://workday.github.io/canvas-kit/?path=/docs/guides-upgrade-guides-v14-0-visual-changes--docs) guide.
 
 The following components have been updated:
 
-- `Breadcrumbs`
-  - [#3270](https://github.com/Workday/canvas-kit/pull/3270)
-  - [#3447](https://github.com/Workday/canvas-kit/pull/3447)
+- `Breadcrumbs` [#3270](https://github.com/Workday/canvas-kit/pull/3270),[#3447](https://github.com/Workday/canvas-kit/pull/3447)
 - `Buttons` [#3394](https://github.com/Workday/canvas-kit/pull/3394)
 - `ColorPicker` (Main) [#3307](https://github.com/Workday/canvas-kit/pull/3307)
 - `ColorPicker` (preview) [#3307](https://github.com/Workday/canvas-kit/pull/3307)
@@ -351,17 +365,32 @@ The following components have been updated:
 
 ### Buttons
 
-#### TertiaryButton
+#### TertiaryButton 🚨
+
+**Breaking Changes**
 
-The `TertiaryButton` component no longer supports the `isThemable` prop. To customize the appearance
-of `TertiaryButton`, use the `cs` prop for custom styles or the `colors` prop for palette-based
-color overrides.
+- The `TertiaryButton` component no longer supports the `isThemable` prop. To customize the appearance
+  of `TertiaryButton`, use the `cs` prop for custom styles or the `colors` prop for palette-based
+  color overrides.
+- The shape of `TertiaryButton` has changed to have rounded corners, aligning with other buttons and
+  our new brand direction.
 
-The shape of `TertiaryButton` has changed to have rounded corners, aligning with other buttons and
-our new brand direction.
+**Before in v13**
+
+```tsx
+<TertiaryButton isThemable>Themable Button</TertiaryButton>
+```
+
+**After in v14**
+
+```tsx
+<TertiaryButton cs={{/* custom styles */}}>Custom Button</TertiaryButton>
+// OR
+<TertiaryButton colors={{/* palette colors */}}>Custom Button</TertiaryButton>
+```
 
 If you need to override default styles, follow
-[this guide](https://workday.github.io/canvas-kit/?path=/docs/components-buttons--docs#custom-styles)
+[this guide](https://workday.github.io/canvas-kit/?path=/docs/components-buttons--docs#custom-styles).
 
 ### Card 🚨
 
@@ -370,12 +399,12 @@ If you need to override default styles, follow
 We've rebranded the `Card` component to align with our new brand directions and provide better
 visual hierarchy and more flexible styling options. The following changes have been made:
 
-#### Default Card No Longer Has Shadow
+#### Default Card No Longer Has a Box Shadow
 
-The default `Card` variant no longer includes a shadow, creating a cleaner, flatter appearance that
+The default `Card` variant no longer includes a box shadow, creating a cleaner, flatter appearance that
 aligns with our new brand's emphasis on simplicity and clarity. This is a **visual breaking change**
-that may affect your application's visual hierarchy. If your design requires shadow you can added
-through `cs` prop.
+that may affect your application's visual hierarchy. If your design requires shadow you can add it
+through the `cs` prop.
 
 **Before in v13**
 
@@ -387,12 +416,15 @@ through `cs` prop.
 ```
 
 **After in v14**
+Only do this if you need a shadow. Otherwise, adhere to the default styling.
 
 ```tsx
+import {system} from '@workday/canvas-tokens-web';
+
 <Card cs={{boxShadow: system.depth[1]}}>
   <Card.Heading>Card Title</Card.Heading>
   <Card.Body>Card content with shadow</Card.Body>
-</Card>
+</Card>;
 ```
 
 #### New Card Variants
@@ -407,7 +439,7 @@ We've added two new variants to provide more styling flexibility:
 The `variant` prop is optional - if no variant is specified, the card will use the default styling.
 
 ```tsx
-// Default card (no variant prop needed)
+// Default card (no variant prop needed) with a border and no box shadow
 <Card>
   <Card.Heading>Default Card</Card.Heading>
   <Card.Body>Default styling with borders, no shadow</Card.Body>
@@ -428,11 +460,11 @@ The `variant` prop is optional - if no variant is specified, the card will use t
 
 #### Gap Instead of Margins
 
-We've replaced the individual margins on `Card.Heading` and `Card.Body` with a `gap` prop on the
-card container. The card now uses `display: flex` with `flex-direction: column` by default, and the
-`gap` prop provides consistent spacing between all direct children. This provides more consistent
-spacing and better control over the layout. This is a **visual breaking change** that may affect the
-spacing between card elements.
+We've replaced the individual margins on `Card.Heading` and `Card.Body` with `gap`. The card now
+uses `display: flex` with `flex-direction: column` by default, and the `gap` prop provides
+consistent spacing between all direct children. This provides more consistent spacing and better
+control over the layout. This is a **visual breaking change** that may affect the spacing between
+card elements.
 
 **Before in v13**
 
@@ -466,7 +498,7 @@ emphasis for the badge.
 ```tsx
 <CountBadge /> // Default count badge with high emphasis
 <CountBadge variant="inverse" /> // Inverse default count badge
-// new
+// New emphasis prop
 <CountBadge emphasis="low" /> // Default count badge with low emphasis
 <CountBadge variant="inverse" emphasis="low" /> // Inverse count badge with low emphasis
 ```
@@ -476,9 +508,9 @@ emphasis for the badge.
 **PRs:** [#3389](https://github.com/Workday/canvas-kit/pull/3389),
 [#3430](https://github.com/Workday/canvas-kit/pull/3430)
 
-- `<Expandable.Target>` hover state has been update to use `system.color.bg.alt.soft` instead of
+- `<Expandable.Target>` hover state has been updated to use `system.color.bg.alt.soft` instead of
   `system.color.bg.alt.default` to match our new brand directions.
-- The `focus` state has been update to use `system.color.border.primary.default` to ensure the same
+- The `focus` state has been updated to use `system.color.border.primary.default` to ensure the same
   focus state color across all components.
 - `Expandable.Avatar` has been updated to use the `Avatar` component from Preview. This change
   requires that you update the `altText` prop to `name`.
@@ -487,14 +519,14 @@ emphasis for the badge.
 
 These changes are only **visual** and should not affect the functionality of the component.
 
-### Hyperlink and External Hyperlink
+### Hyperlink and ExternalHyperlink
 
 **PR:** [#3390](https://github.com/Workday/canvas-kit/pull/3390)
 
 - `Hyperlink` and `ExternalHyperlink` now have a `standalone` and `standaloneInverse` variant. This
   removes the underline text decoration for use outside the context of body text.
 
-**HyperLink and ExternalHyperlink in v14**
+**Hyperlink and ExternalHyperlink in v14**
 
 ```tsx
 <Hyperlink variant="standalone" href="#hyperlink">Hyperlink</Hyperlink>
@@ -510,16 +542,19 @@ These changes are only **visual** and should not affect the functionality of the
 
 **PR:** [#3393](https://github.com/Workday/canvas-kit/pull/3393)
 
-- We've updated the colors to match brand refresh. The default color changes from
+- We've updated the colors to match our brand refresh. The default color changes from
   `system.color.bg.alt.strong` to `system.color.bg.muted.strong`.
-- `LoadingDots` now has a `inverse` variant. Use this variant when the Loading Dots are on a dark
+- `LoadingDots` now has an `inverse` variant. Use this variant when the Loading Dots are on a dark
   background or image.
 
+**After in v14**
+
 ```tsx
+// Use inverse variant when the Loading Dots are on a dark background or image
 <LoadingDots variant="inverse" />
 ```
 
-### Pill
+### Pill (Preview)
 
 **PRs:** [#3430](https://github.com/Workday/canvas-kit/pull/3430),
 [#3446](https://github.com/Workday/canvas-kit/pull/3446)
@@ -532,7 +567,7 @@ These changes are only **visual** and should not affect the functionality of the
 - The `Pill` component no longer supports `'default'` as a value for the `variant` prop. If the
   `variant` prop is not provided, the component will use its default styling.
 
-- `readyOnlyPillStencil` and `removeablePillStencil` have been removed due to some styling clean up.
+- `readyOnlyPillStencil` and `removeablePillStencil` have been removed due to some styling cleanup.
   Please use `pillStencil` instead.
 
 **Before in v13**
@@ -553,7 +588,7 @@ These changes are only **visual** and should not affect the functionality of the
 </Pill>
 ```
 
-### Search Form 🚨
+### SearchForm 🚨
 
 **PR:** [#3303](https://github.com/Workday/canvas-kit/pull/3303)
 
@@ -564,20 +599,19 @@ These changes are only **visual** and should not affect the functionality of the
 
 ```tsx
 const customTheme = {
-	background: colors.cinnamon600,
-	backgroundFocus: colors.frenchVanilla100,
-	placeholderColor: colors.frenchVanilla100,
-	placeholderColorFocus: colors.blackPepper400,
-	boxShadow: ['10px 5px 5px red', '60px -16px teal']
-	boxShadowFocus: ['10px 5px 5px red', '60px -16px teal']
+  background: colors.cinnamon600,
+  backgroundFocus: colors.frenchVanilla100,
+  placeholderColor: colors.frenchVanilla100,
+  placeholderColorFocus: colors.blackPepper400,
+  boxShadow: ['10px 5px 5px red', '60px -16px teal'],
+  boxShadowFocus: ['10px 5px 5px red', '60px -16px teal']
 } as SearchThemeAttributes;
-	//...
 
-	<SearchForm
-	searchTheme={customTheme}
-	autocompleteItems={menuItems}
-	onInputChange={filterMenuItems}
-	onSubmit={handleSubmit}
+<SearchForm
+  searchTheme={customTheme}
+  autocompleteItems={menuItems}
+  onInputChange={filterMenuItems}
+  onSubmit={handleSubmit}
 />
 ```
 
@@ -592,14 +626,13 @@ const customTheme = {
   boxShadow: '10px 5px 5px red',
   boxShadowFocus: '10px 5px 5px red',
 } as SearchThemeAttributes;
-//...
 
 <SearchForm
   searchTheme={customTheme}
   autocompleteItems={menuItems}
   onInputChange={filterMenuItems}
   onSubmit={handleSubmit}
-/>;
+/>
 ```
 
 - `SearchTheme` enum type has been updated to have string values `light`, `dark` and `transparent`.
@@ -610,20 +643,40 @@ const customTheme = {
 
 **PR:** [#3287](https://github.com/Workday/canvas-kit/pull/3287)
 
-Preview `StatusIndicator` is a rounder and more vibrant base emphasis (`low`).
+Preview `StatusIndicator` is rounder and more vibrant with base emphasis (`low`).
 
 Variant names of the preview `StatusIndicator` have been updated by the following mapping:
 
-- `blue` -> `primary`
-- `green` -> `success`
-- `orange` -> `caution`
-- `red` -> `critical`
-- `gray` -> `neutral`
+- `blue` → `primary`
+- `green` → `success`
+- `orange` → `caution`
+- `red` → `critical`
+- `gray` → `neutral`
 
 The `StatusIndicatorVariant` type has been updated to contain the new variant names listed above. If
 you use the old variant values, update to use the new ones mapped above. It has also been
 deprecated. Use `StatusIndicatorProps['variant']` instead.
 
+**Before in v13**
+
+```tsx
+<StatusIndicator variant="blue" />
+<StatusIndicator variant="green" />
+<StatusIndicator variant="orange" />
+<StatusIndicator variant="red" />
+<StatusIndicator variant="gray" />
+```
+
+**After in v14**
+
+```tsx
+<StatusIndicator variant="primary" />
+<StatusIndicator variant="success" />
+<StatusIndicator variant="caution" />
+<StatusIndicator variant="critical" />
+<StatusIndicator variant="neutral" />
+```
+
 ## Deprecations
 
 We add the [@deprecated](https://jsdoc.app/tags-deprecated.html) JSDoc tag to code we plan to remove
@@ -642,10 +695,10 @@ We've deprecated the `Avatar` component in `@workday/canvas-kit-react` Main pack
 ```tsx
 import { Avatar } from '@workday/canvas-kit-react/avatar';
 
-// For Avatars that where divs
+// For Avatars that were divs
 <Avatar altText="John Doe" size="extraExtraLarge" as="div" url={yourImageUrl} />
 
-// For Avatars that where buttons
+// For Avatars that were buttons
 <Avatar altText="John Doe" onClick={() => console.log('Avatar clicked')} />
 ```
 
@@ -654,8 +707,8 @@ import { Avatar } from '@workday/canvas-kit-react/avatar';
 ```tsx
 import {Avatar} from '@workday/canvas-kit-preview-react/avatar';
 // name is used as a fallback if the image url is broken or still loading
-// variant light or dark are not used. Instead, variant defines the color of the Avatar
-<Avatar name="John Doe" size="extraExtraLarge" variant="teal" url={yourImageUrl} />;
+// variant defines the color of the Avatar
+<Avatar name="John Doe" size="extraExtraLarge" variant="teal" url={yourImageUrl} />
 ```
 
 If you need to render a `button` element use the `BaseAvatar` component.
@@ -671,7 +724,7 @@ import {BaseAvatar} from '@workday/canvas-kit-preview-react/avatar';
   onClick={() => console.log('Avatar clicked')}
 >
   <BaseAvatar.Name name="John Doe" />
-</BaseAvatar>;
+</BaseAvatar>
 ```
 
 ### Combobox (Labs)
@@ -687,7 +740,7 @@ The Radio component in `@workday/canvas-kit-react/radio` has been deprecated. Pl
 [Radio](https://workday.github.io/canvas-kit/?path=/docs/components-inputs-radio--docs) component
 from the same package, which offers improved accessibility and API consistency.
 
-### Search Form (Labs)
+### SearchForm (Labs)
 
 **PR:** [#3469](https://github.com/Workday/canvas-kit/pull/3469)
 
@@ -714,9 +767,9 @@ functionality.
 
 The legacy tokens from `@workday/canvas-kit-react/tokens` are now deprecated. Please use the new
 [Canvas Tokens Web](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs)
-package (`@workday/canvas-tokens-web`) for all token usage. Follow
-[a migration guide](https://workday.github.io/canvas-kit?path=/docs/guides-tokens-migration-overview--docs)
-for smootier upgrade.
+package (`@workday/canvas-tokens-web`) for all token usage. Follow the
+[migration guide](https://workday.github.io/canvas-kit?path=/docs/guides-tokens-migration-overview--docs)
+for a smoother upgrade.
 
 ## Removals
 
@@ -730,10 +783,10 @@ promoted or replaced a component or utility.
 Long overdue, but a sign of moving forward, we are removing our `DeprecatedButton`. Our design
 system supported this for quite some time, but with the advancement in theming, our components API
 and our flexibility, it is time for us to finally remove this component. This component has served
-as a reminder of how far we've come and it part we're thankful for this change.
+as a reminder of how far we've come and we're thankful for this change.
 
-Al though unlikely, but not impossible, if you were using `DeprecatedButton` please use our flexible
-and themable buttons like `PrimaryButton`, `ScondaryButton` or `TertiaryButton`.
+Although unlikely, if you were using `DeprecatedButton` please use our flexible
+and themable buttons like `PrimaryButton`, `SecondaryButton` or `TertiaryButton`.
 
 ### Input Provider
 
@@ -745,7 +798,7 @@ browser heuristics to determine when an element should receive visual focus styl
 information, please view the
 [MDN docs on `:focus-visible`](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible).
 
-If you are trying to apply focus styles to our components, we strongly avise to use `:focus-visible`
+If you are trying to apply focus styles to our components, we strongly advise using the `:focus-visible`
 pseudo selector.
 
 ```tsx
@@ -759,11 +812,11 @@ const buttonStyles = createStyles({
 })
 
 <PrimaryButton cs={buttonStyles}>
-	Click Me
+  Click Me
 </PrimaryButton>
 ```
 
-### Menu (preview)
+### Menu (Preview)
 
 **PR:** [#3353](https://github.com/Workday/canvas-kit/pull/3353)
 
@@ -776,7 +829,7 @@ We've removed `Menu` from `@workday/canvas-kit-preview-react` package. Please us
 The `readyOnlyPillStencil` and `removeablePillStencil` utilities have been removed from the Pill
 package. Please use `pillStencil` instead.
 
-### Text Area (preview)
+### Text Area (Preview)
 
 **PR:** [#3471](https://github.com/Workday/canvas-kit/pull/3471)
 
@@ -846,19 +899,35 @@ import {FormField} from '@workday/canvas-kit-react/form-field';
 
 ## Troubleshooting
 
-- When upgrading to the latest major version of Canvas Kit, all related Canvas Kit packages should
+### Common Issues
+
+- **Dependency Conflicts**: When upgrading to the latest major version of Canvas Kit, all related Canvas Kit packages should
   be updated at the same time:
-  - `"@workday/canvas-kit-react": "^13.5.6"` -> `"@workday/canvas-kit-react": "^14.0.0"`
-  - `"@workday/canvas-kit-styling": "^13.5.6"` -> `"@workday/canvas-kit-styling": "^14.0.0"`
-  - `"@workday/canvas-kit-preview-react": "^13.5.6"` ->
+  - `"@workday/canvas-kit-react": "^13.5.6"` → `"@workday/canvas-kit-react": "^14.0.0"`
+  - `"@workday/canvas-kit-styling": "^13.5.6"` → `"@workday/canvas-kit-styling": "^14.0.0"`
+  - `"@workday/canvas-kit-preview-react": "^13.5.6"` →
     `"@workday/canvas-kit-preview-react": "^14.0.0"`
-  - `"@workday/canvas-kit-labs-react": "^13.5.6"` -> `"@workday/canvas-kit-labs-react": "^14.0.0"`
-- Our components rely on the `@workday/canvas-tokens-web` package which provides our CSS variables
+  - `"@workday/canvas-kit-labs-react": "^13.5.6"` → `"@workday/canvas-kit-labs-react": "^14.0.0"`
+
+- **Token Issues**: Our components rely on the `@workday/canvas-tokens-web` package which provides our CSS variables
   and ensures the correct styling of our components. Make sure to upgrade to the latest version of
   Canvas Tokens Web and install it correctly. For more information,
   [view our docs](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).
 
+- **Color Discrepancies**: If you notice visual differences after upgrading, this may be due to the change from `chroma.js` to `oklch` color generation. Consider providing explicit color values in your theme configuration.
+
+- **Build Errors**: If you encounter build errors after running the codemod, ensure your linter is run as the codemod's formatting may not match your project conventions.
+
 ## Glossary
 
-For an overview of the different packages we provide, plase view our docs
-[here](https://workday.github.io/canvas-kit/?path=/docs/guides-packages--docs).
+For an overview of the different packages we provide, please view our docs
+[here](https://workday.github.io/canvas-kit/?path=/docs/guides-packages--docs).
+
+### Main
+Components in the Main package are stable and ready for production use.
+
+### Preview
+Components in the Preview package are mostly stable but may still receive breaking changes before being promoted to Main.
+
+### Labs
+Components in the Labs package are experimental and may receive significant changes or be removed entirely.

package/dist/mdx/14.0-VISUAL-CHANGES.mdx

@@ -0,0 +1,44 @@
+import {Graphic} from '@workday/canvas-kit-react/icon';
+
+import avatarImage from './images/v14-avatar.png';
+import breadcrumbsImage from './images/v14-breadcrumbs.png';
+import cardImage from './images/v14-card.png';
+import checkboxImage from './images/v14-checkbox.png';
+import countBadgeImage from './images/v14-count-badge.png';
+import expandableImage from './images/v14-expandable.png';
+import infoHighlightImage from './images/v14-info-highlight.png';
+import loadingDotsImage from './images/v14-loading-dots.png';
+import pillImage from './images/v14-pill.png';
+import primaryButtonImage from './images/v14-primary-button.png';
+import radioImage from './images/v14-radio.png';
+import secondaryButtonImage from './images/v14-secondary-button.png';
+import selectImage from './images/v14-select.png';
+import statusIndicatorImage from './images/v14-status-indicator-preview.png';
+import tabsImage from './images/v14-tabs.png';
+import tertiaryButtonImage from './images/v14-tertiary-button.png';
+import textAreaImage from './images/v14-text-area.png';
+import textInputImage from './images/v14-text-input.png';
+
+
+# Canvas Kit 14.0 Visual Changes
+
+This guide contains an overview of the changes in Canvas Kit v14. If you have any issues, feel free to report them [here](https://github.com/Workday/canvas-kit/issues). For a mode detailed overview of the changes in v14, please view our [v14 Upgrade Guide](https://workday.github.io/canvas-kit/?path=/docs/guides-upgrade-guides-v14-0-overview--docs).
+
+<Graphic src={{url: avatarImage}} />
+<Graphic src={{url: breadcrumbsImage}} />
+<Graphic src={{url: cardImage}} />
+<Graphic src={{url: checkboxImage}} />
+<Graphic src={{url: countBadgeImage}} />
+<Graphic src={{url: expandableImage}} />
+<Graphic src={{url: infoHighlightImage}} />
+<Graphic src={{url: loadingDotsImage}} />
+<Graphic src={{url: pillImage}} />
+<Graphic src={{url: primaryButtonImage}} />
+<Graphic src={{url: radioImage}} />
+<Graphic src={{url: secondaryButtonImage}} />
+<Graphic src={{url: selectImage}} />
+<Graphic src={{url: statusIndicatorImage}} />
+<Graphic src={{url: tabsImage}} />
+<Graphic src={{url: tertiaryButtonImage}} />
+<Graphic src={{url: textAreaImage}} />
+<Graphic src={{url: textInputImage}} />