From 5b29e8bfd00fa3119779af5a1f23c8cca3c9c0bf Mon Sep 17 00:00:00 2001
From: "manuel.carrera" <manuel.carrera@workday.com>
Date: Wed, 18 Feb 2026 13:30:09 -0700
Subject: [PATCH 01/12] fix: Add backwards compatability with canvas provider

---
 modules/react/common/lib/CanvasProvider.tsx | 180 ++++++++++++++++++--
 1 file changed, 163 insertions(+), 17 deletions(-)

diff --git a/modules/react/common/lib/CanvasProvider.tsx b/modules/react/common/lib/CanvasProvider.tsx
index 926cc61df6..0b0f87f3f5 100644
--- a/modules/react/common/lib/CanvasProvider.tsx
+++ b/modules/react/common/lib/CanvasProvider.tsx
@@ -2,7 +2,7 @@ import {CacheProvider, Theme, ThemeProvider} from '@emotion/react';
 import * as React from 'react';
 
 import {createStyles, getCache, maybeWrapCSSVariables} from '@workday/canvas-kit-styling';
-import {base, brand} from '@workday/canvas-tokens-web';
+import {base, brand, system} from '@workday/canvas-tokens-web';
 
 import {PartialEmotionCanvasTheme, defaultCanvasTheme, useTheme} from './theming';
 
@@ -26,6 +26,42 @@ const mappedKeys = {
   contrast: 'accent',
 };
 
+/**
+ * Mapping from deprecated theme palette keys to new numerical brand tokens.
+ * This ensures backwards compatibility when consumers use the old theme format.
+ * For example: palette.primary.main -> brand.primary600
+ */
+const numericalTokenMapping = {
+  lightest: '25',
+  lighter: '50',
+  light: '200',
+  main: '600',
+  dark: '700',
+  darkest: '800',
+} as const;
+
+/**
+ * Mapping from deprecated theme palette colors to new brand token names.
+ * For example: 'primary' -> 'primary', 'error' -> 'critical', 'success' -> 'positive'
+ */
+const brandColorMapping = {
+  primary: 'primary',
+  error: 'critical',
+  success: 'positive',
+  alert: 'caution',
+  neutral: 'neutral',
+} as const;
+
+/**
+ * Mapping from deprecated common palette keys to new brand.common tokens.
+ */
+const commonTokenMapping = {
+  focusOutline: brand.common.focus, // maps to brand.primary500
+  alertInner: brand.common.caution.inner, // maps to brand.caution400
+  alertOuter: brand.common.caution.outer, // maps to brand.caution500
+  errorInner: brand.common.critical, // maps to brand.critical500
+} as const;
+
 /**
  * If you wish to reset the theme to the default, apply this class on the CanvasProvider.
  */
@@ -84,32 +120,142 @@ export const useCanvasThemeToCssVars = (
   const className = (elemProps.className || '').split(' ').concat(defaultBranding).join(' ');
   const style = elemProps.style || {};
   const {palette} = filledTheme.canvas;
+
   (['common', 'primary', 'error', 'alert', 'success', 'neutral'] as const).forEach(color => {
     if (color === 'common') {
       (['focusOutline', 'alertInner', 'alertOuter', 'errorInner'] as const).forEach(key => {
         if (palette.common[key] !== defaultCanvasTheme.palette.common[key]) {
+          const value = maybeWrapCSSVariables(palette.common[key]);
+
+          // Set deprecated token for backwards compatibility
           //@ts-ignore
-          style[brand.common.focusOutline] = maybeWrapCSSVariables(palette.common.focusOutline);
-          //@ts-ignore
-          style[brand.common.alertInner] = maybeWrapCSSVariables(palette.common.alertInner);
-          //@ts-ignore
-          style[brand.common.alertOuter] = maybeWrapCSSVariables(palette.common.alertOuter);
+          style[brand.common[key]] = value;
+
+          // Forward to new brand.common tokens
           //@ts-ignore
-          style[brand.common.errorInner] = maybeWrapCSSVariables(palette.common.errorInner);
+          style[commonTokenMapping[key]] = value;
+
+          // Additional system token forwarding for focusOutline
+          if (key === 'focusOutline') {
+            // system.color.brand.focus.primary -> brand.primary.500 (via brand.common.focus)
+            // @ts-ignore
+            style[system.color.brand.focus.primary] = value;
+            // system.color.brand.border.primary -> brand.primary.500
+            // @ts-ignore
+            style[system.color.brand.border.primary] = value;
+          }
         }
       });
-    }
-    (['lightest', 'lighter', 'light', 'main', 'dark', 'darkest', 'contrast'] as const).forEach(
-      key => {
-        // We only want to set custom colors if they do not match the default. The `defaultBranding` class will take care of the rest.
-        //@ts-ignore
-        if (palette[color][key] !== defaultCanvasTheme.palette[color][key]) {
-          // @ts-ignore
-          style[brand[color][mappedKeys[key]]] = maybeWrapCSSVariables(palette[color][key]);
+    } else {
+      (['lightest', 'lighter', 'light', 'main', 'dark', 'darkest', 'contrast'] as const).forEach(
+        key => {
+          // We only want to set custom colors if they do not match the default. The `defaultBranding` class will take care of the rest.
+          //@ts-ignore
+          if (palette[color][key] !== defaultCanvasTheme.palette[color][key]) {
+            const value = maybeWrapCSSVariables(palette[color][key]);
+
+            // Set deprecated token (e.g., brand.primary.base) for backwards compatibility
+            // @ts-ignore
+            style[brand[color][mappedKeys[key]]] = value;
+
+            // Forward to new numerical brand tokens (e.g., brand.primary600)
+            // Skip 'contrast' as it doesn't map to numerical tokens
+            if (key !== 'contrast' && key in numericalTokenMapping) {
+              const newBrandColor = brandColorMapping[color as keyof typeof brandColorMapping];
+              const numericalSuffix =
+                numericalTokenMapping[key as keyof typeof numericalTokenMapping];
+
+              // @ts-ignore - Dynamically access brand tokens like brand.primary600
+              const numericalToken = brand[newBrandColor + numericalSuffix];
+              if (numericalToken) {
+                // @ts-ignore
+                style[numericalToken] = value;
+              }
+
+              // Forward to all relevant system.color.brand.* tokens
+              // These system tokens reference the numerical brand tokens, so updating them ensures full compatibility
+              if (key === 'main') {
+                // system.color.brand.accent.{color} -> brand.{color}.600 (except caution -> 400)
+                // @ts-ignore
+                const systemAccentToken = system.color.brand.accent[newBrandColor];
+                if (systemAccentToken) {
+                  // @ts-ignore
+                  style[systemAccentToken] = value;
+                }
+
+                // system.color.brand.fg.{color}.default -> brand.{color}.600
+                // @ts-ignore
+                const systemFgToken = system.color.brand.fg[newBrandColor]?.default;
+                if (systemFgToken) {
+                  // @ts-ignore
+                  style[systemFgToken] = value;
+                }
+
+                // system.color.brand.focus.primary (maps to brand.primary.500 per docs)
+                // For primary only, update focus border when 'main' changes
+                if (newBrandColor === 'primary') {
+                  // Calculate a reasonable focus color based on the main color
+                  // We'll use the main value since brand.primary.500 derives from it
+                  // @ts-ignore
+                  const focusToken = system.color.brand.focus.primary;
+                  if (focusToken) {
+                    // @ts-ignore
+                    style[focusToken] = value;
+                  }
+                }
+              } else if (key === 'dark') {
+                // system.color.brand.fg.{color}.strong -> brand.{color}.700
+                // @ts-ignore
+                const systemFgStrongToken = system.color.brand.fg[newBrandColor]?.strong;
+                if (systemFgStrongToken) {
+                  // @ts-ignore
+                  style[systemFgStrongToken] = value;
+                }
+
+                // system.color.brand.fg.selected -> brand.primary.700 (for primary only)
+                if (newBrandColor === 'primary') {
+                  // @ts-ignore
+                  const selectedToken = system.color.brand.fg.selected;
+                  if (selectedToken) {
+                    // @ts-ignore
+                    style[selectedToken] = value;
+                  }
+                }
+              } else if (key === 'lighter') {
+                // system.color.brand.surface.{color}.strong -> brand.{color}.A50
+                // Note: A50 tokens are different from regular 50 tokens but we'll forward the lighter value
+                // @ts-ignore
+                const surfaceStrongToken = system.color.brand.surface[newBrandColor]?.strong;
+                if (surfaceStrongToken) {
+                  // @ts-ignore
+                  style[surfaceStrongToken] = value;
+                }
+
+                // system.color.brand.surface.selected -> brand.primary.A50 (for primary only)
+                if (newBrandColor === 'primary') {
+                  // @ts-ignore
+                  const selectedSurfaceToken = system.color.brand.surface.selected;
+                  if (selectedSurfaceToken) {
+                    // @ts-ignore
+                    style[selectedSurfaceToken] = value;
+                  }
+                }
+              } else if (key === 'lightest') {
+                // system.color.brand.surface.{color}.default -> brand.{color}.A25
+                // @ts-ignore
+                const surfaceDefaultToken = system.color.brand.surface[newBrandColor]?.default;
+                if (surfaceDefaultToken) {
+                  // @ts-ignore
+                  style[surfaceDefaultToken] = value;
+                }
+              }
+            }
+          }
         }
-      }
-    );
+      );
+    }
   });
+
   return {...elemProps, className, style};
 };
 

From e604692bc90559d0a474cee401807d6ce6e3df95 Mon Sep 17 00:00:00 2001
From: "manuel.carrera" <manuel.carrera@workday.com>
Date: Wed, 18 Feb 2026 16:40:49 -0700
Subject: [PATCH 02/12] fix: Add backwards compatability with tokens

---
 modules/react/common/lib/CanvasProvider.tsx | 65 +++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/modules/react/common/lib/CanvasProvider.tsx b/modules/react/common/lib/CanvasProvider.tsx
index 0b0f87f3f5..9455ffa220 100644
--- a/modules/react/common/lib/CanvasProvider.tsx
+++ b/modules/react/common/lib/CanvasProvider.tsx
@@ -54,6 +54,51 @@ const brandColorMapping = {
 
 /**
  * Mapping from deprecated common palette keys to new brand.common tokens.
+ *
+ * ## Brandable System Tokens
+ *
+ * These are all the `system.color.brand.*` tokens that can be customized via theming.
+ * Each token references a brand token that can be overridden through the CanvasProvider theme prop.
+ *
+ * ### Focus Tokens
+ * - `system.color.brand.focus.primary` → `brand.primary.500` → Controlled by `palette.primary.main` or `focusOutline`
+ * - `system.color.brand.focus.critical` → `brand.critical.500` → Controlled by `palette.error.dark` or `errorInner`
+ * - `system.color.brand.focus.caution.inner` → `brand.caution.400` → Controlled by `palette.alert.main` or `alertInner`
+ * - `system.color.brand.focus.caution.outer` → `brand.caution.500` → Controlled by `palette.alert.dark` or `alertOuter`
+ *
+ * ### Border Tokens
+ * - `system.color.brand.border.primary` → `brand.primary.500` → Controlled by `palette.primary.main` or `focusOutline`
+ * - `system.color.brand.border.critical` → `brand.critical.500` → Controlled by `palette.error.dark` or `errorInner`
+ * - `system.color.brand.border.caution` → `brand.caution.500` → Controlled by `palette.alert.dark` or `alertOuter`
+ *
+ * ### Surface Tokens
+ * - `system.color.brand.surface.primary.default` → `brand.primary.A25` → Controlled by `palette.primary.lightest`
+ * - `system.color.brand.surface.primary.strong` → `brand.primary.A50` → Controlled by `palette.primary.lighter`
+ * - `system.color.brand.surface.critical.default` → `brand.critical.A25` → Controlled by `palette.error.lightest`
+ * - `system.color.brand.surface.critical.strong` → `brand.critical.A50` → Controlled by `palette.error.lighter`
+ * - `system.color.brand.surface.caution.default` → `brand.caution.A25` → Controlled by `palette.alert.lightest`
+ * - `system.color.brand.surface.caution.strong` → `brand.caution.A50` → Controlled by `palette.alert.lighter`
+ * - `system.color.brand.surface.positive.default` → `brand.positive.A25` → Controlled by `palette.success.lightest`
+ * - `system.color.brand.surface.positive.strong` → `brand.positive.A50` → Controlled by `palette.success.lighter`
+ * - `system.color.brand.surface.selected` → `brand.primary.A50` → Controlled by `palette.primary.lighter`
+ *
+ * ### Accent Tokens
+ * - `system.color.brand.accent.primary` → `brand.primary.600` → Controlled by `palette.primary.main`
+ * - `system.color.brand.accent.critical` → `brand.critical.600` → Controlled by `palette.error.main`
+ * - `system.color.brand.accent.caution` → `brand.caution.400` → Controlled by `palette.alert.main`
+ * - `system.color.brand.accent.positive` → `brand.positive.600` → Controlled by `palette.success.main`
+ * - `system.color.brand.accent.action` → `brand.primary.600` → Controlled by `palette.primary.main`
+ *
+ * ### Foreground (Text/Icon) Tokens
+ * - `system.color.brand.fg.primary.default` → `brand.primary.600` → Controlled by `palette.primary.main`
+ * - `system.color.brand.fg.primary.strong` → `brand.primary.700` → Controlled by `palette.primary.dark`
+ * - `system.color.brand.fg.critical.default` → `brand.critical.600` → Controlled by `palette.error.main`
+ * - `system.color.brand.fg.critical.strong` → `brand.critical.700` → Controlled by `palette.error.dark`
+ * - `system.color.brand.fg.caution.default` → `brand.caution.600` → Controlled by `palette.alert.darkest`
+ * - `system.color.brand.fg.caution.strong` → `brand.caution.700` → Controlled by `palette.alert.dark` (Note: no direct mapping, inherits default)
+ * - `system.color.brand.fg.positive.default` → `brand.positive.600` → Controlled by `palette.success.main`
+ * - `system.color.brand.fg.positive.strong` → `brand.positive.700` → Controlled by `palette.success.dark`
+ * - `system.color.brand.fg.selected` → `brand.primary.700` → Controlled by `palette.primary.dark`
  */
 const commonTokenMapping = {
   focusOutline: brand.common.focus, // maps to brand.primary500
@@ -144,6 +189,26 @@ export const useCanvasThemeToCssVars = (
             // @ts-ignore
             style[system.color.brand.border.primary] = value;
           }
+
+          // Additional system token forwarding for alertInner
+          if (key === 'alertInner') {
+            // Forward alertInner to system.color.brand.focus.caution.inner
+            // This token is used by components (e.g., TextInput with error="caution")
+            // for inner focus ring styling. Maps to brand.caution400 via brand.common.caution.inner.
+            // This ensures backwards compatibility when users customize alertInner in their theme.
+            // @ts-ignore
+            style[system.color.brand.focus.caution.inner] = value;
+          }
+
+          // Additional system token forwarding for alertOuter
+          if (key === 'alertOuter') {
+            // Forward alertOuter to system.color.brand.border.caution
+            // This token is used by components (e.g., TextInput with error="caution")
+            // for border and outer focus ring styling. Maps to brand.caution500 via brand.common.caution.outer.
+            // This ensures backwards compatibility when users customize alertOuter in their theme.
+            // @ts-ignore
+            style[system.color.brand.border.caution] = value;
+          }
         }
       });
     } else {

From 467e73740d975b3c91d5799ab957cf940fd56546 Mon Sep 17 00:00:00 2001
From: "manuel.carrera" <manuel.carrera@workday.com>
Date: Tue, 24 Feb 2026 09:19:13 -0700
Subject: [PATCH 03/12] fix: Update flashing of theme

---
 .../react/popup/lib/hooks/usePopupStack.ts    | 54 +++++++++++--------
 1 file changed, 32 insertions(+), 22 deletions(-)

diff --git a/modules/react/popup/lib/hooks/usePopupStack.ts b/modules/react/popup/lib/hooks/usePopupStack.ts
index 52b089daa7..ba2c03e300 100644
--- a/modules/react/popup/lib/hooks/usePopupStack.ts
+++ b/modules/react/popup/lib/hooks/usePopupStack.ts
@@ -1,8 +1,12 @@
-import {Theme, ThemeContext} from '@emotion/react';
 import React from 'react';
 
 import {PopupStack} from '@workday/canvas-kit-popup-stack';
-import {isElementRTL, useCanvasThemeToCssVars, useLocalRef} from '@workday/canvas-kit-react/common';
+import {
+  isElementRTL,
+  useCanvasThemeToCssVars,
+  useLocalRef,
+  useTheme,
+} from '@workday/canvas-kit-react/common';
 
 /**
  * **Note:** If you're using {@link Popper}, you do not need to use this hook directly.
@@ -51,8 +55,10 @@ export const usePopupStack = <E extends HTMLElement>(
   target?: HTMLElement | React.RefObject<HTMLElement>
 ): React.RefObject<HTMLElement> => {
   const {elementRef, localRef} = useLocalRef(ref);
-  const theme = React.useContext(ThemeContext as React.Context<Theme>);
-  const {style} = useCanvasThemeToCssVars(theme, {});
+  // Use useTheme() (no args) so we get the filled theme from Emotion context—same as CanvasProvider.
+  // Passing raw context can miss filling; useTheme() ensures palette + system.brand tokens are resolved.
+  const filledTheme = useTheme();
+  const {style} = useCanvasThemeToCssVars(filledTheme, {});
   const firstLoadRef = React.useRef(true); // React 19 can call a useState more than once, so we need to track if we've already created a container
 
   // useState function input ensures we only create a container once.
@@ -65,6 +71,28 @@ export const usePopupStack = <E extends HTMLElement>(
     }
     return localRef.current;
   });
+
+  // Forward only theme overrides (style) to the popup container when a theme was provided via
+  // CanvasProvider theme prop. We do NOT apply defaultBranding (className) so we don't create a
+  // cascade barrier—only the CSS variables the consumer overrode are set. This effect runs
+  // before PopupStack.add below so the container has the theme before it's shown (avoids blue→magenta flash).
+  React.useLayoutEffect(() => {
+    const element = localRef.current;
+    if (!element) {
+      return undefined;
+    }
+    const styleKeys = Object.keys(style);
+    if (styleKeys.length === 0) {
+      return undefined;
+    }
+    for (const key of styleKeys) {
+      // @ts-ignore - token keys are CSS custom property names
+      element.style.setProperty(key, style[key]);
+    }
+    // No cleanup: leave theme on container so reopening doesn't flash
+    return undefined;
+  }, [localRef, style]);
+
   // We useLayoutEffect to ensure proper timing of registration of the element to the popup stack.
   // Without this, the timing is unpredictable when mixed with other frameworks. Other frameworks
   // should also register as soon as the element is available
@@ -113,23 +141,5 @@ export const usePopupStack = <E extends HTMLElement>(
     }
   }, [localRef, target]);
 
-  React.useLayoutEffect(() => {
-    const element = localRef.current;
-    const keys = Object.keys(style);
-    if (element && theme) {
-      for (const key of keys) {
-        // @ts-ignore
-        element.style.setProperty(key, style[key]);
-      }
-      return () => {
-        for (const key of keys) {
-          element.style.removeProperty(key);
-        }
-      };
-    }
-    // No cleanup is needed if element or theme is not set, so return undefined (no effect)
-    return undefined;
-  }, [localRef, style, theme]);
-
   return localRef;
 };

From 690c3c0b189bf3b61ce942a2eb16dc8708b8bd8c Mon Sep 17 00:00:00 2001
From: "manuel.carrera" <manuel.carrera@workday.com>
Date: Tue, 24 Feb 2026 09:23:08 -0700
Subject: [PATCH 04/12] fix: Revert change to include theme context

---
 modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx       | 32 +++++++++++++++++++
 modules/react/common/stories/mdx/Theming.mdx  | 25 +++++++++++++++
 .../react/popup/lib/hooks/usePopupStack.ts    | 15 +++------
 .../stories/visual-testing/Popup.stories.tsx  |  2 +-
 4 files changed, 63 insertions(+), 11 deletions(-)

diff --git a/modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx b/modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx
index 8682d96c05..36cbf91aa4 100644
--- a/modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx
+++ b/modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx
@@ -34,6 +34,8 @@ space tokens, the new tokens aim to add more semantic meaning to allow for bette
   - [Information Highlight ⚡️](#information-highlight-️)
 - [Component Updates](#component-updates)
   - [Buttons](#buttons)
+- [Theming](#theming)
+  - [System Brand Tokens and Brand Tokens](#system-brand-tokens-and-brand-tokens)
 - [Deprecations](#deprecations)
   - [Accent Icon](#accent-icon)
   - [Applet Icon](#applet-icon)
@@ -397,6 +399,36 @@ tokens. These changes are **only visual**.
 `PrimaryButton`, `SecondaryButton`, `DeleteButton`, `TertiaryButton`, `ToolbarButton`,
 `ToolbarDropdownButton`, `Hyperlink`, `ExternalHyperlink`, and `ActionBar`.
 
+## Theming
+
+### System Brand Tokens and Brand Tokens
+
+The relationship between **system brand tokens** (e.g. `system.color.brand.accent.primary`) and **brand tokens** (e.g. `brand.primary600`) has changed. Teams can still set palette values such as `base`, `dark`, `darkest`, `light`, `lightest`, and `lighter` via the `CanvasProvider` theme prop. The mapping inside `CanvasProvider` exists for **backwards compatibility**: when you pass a theme object, we forward those values to both the legacy brand tokens and the system brand tokens so existing usage continues to work.
+
+If you theme via **CSS** (e.g. with `createStyles` and a `className` on `CanvasProvider`), that automatic mapping does not run. You must:
+
+1. **Set the brand token** to your desired color value.
+2. **Set the system brand token** to reference the brand token (so components that use system tokens still pick up your theme).
+
+Example:
+
+```tsx
+import { createStyles } from '@workday/canvas-kit-styling';
+import { brand, system } from '@workday/canvas-tokens-web';
+
+const v4TokensCustomStyles = createStyles({
+  [brand.primary600]: 'darkorange',
+  [system.color.brand.accent.primary]: brand.primary600,
+});
+
+// Apply the class to CanvasProvider (or a scoped container)
+<CanvasProvider className={v4TokensCustomStyles}>
+  <App />
+</CanvasProvider>
+```
+
+Here the **class name** defines the value for the brand token (`brand.primary600`) and sets the system brand token (`system.color.brand.accent.primary`) to that brand token so both the semantic brand layer and the system layer stay in sync. In plain CSS you would do the same: define the brand variable and set the system variable to `var(--cnvs-brand-primary-600)` (or the appropriate token name).
+
 ## Deprecations
 
 We add the [@deprecated](https://jsdoc.app/tags-deprecated.html) JSDoc tag to code we plan to remove
diff --git a/modules/react/common/stories/mdx/Theming.mdx b/modules/react/common/stories/mdx/Theming.mdx
index f392336eb3..e0dbb8a047 100644
--- a/modules/react/common/stories/mdx/Theming.mdx
+++ b/modules/react/common/stories/mdx/Theming.mdx
@@ -186,6 +186,31 @@ const themedBrand = createStyles({
 </CanvasProvider>
 ```
 
+#### System Brand Tokens When Theming via CSS
+
+Components use **system brand tokens** (e.g. `system.color.brand.accent.primary`) for colors. Those system tokens reference **brand tokens** (e.g. `brand.primary600`). When you use the `theme` prop on `CanvasProvider`, we map your palette values to both brand and system tokens for backwards compatibility. When you theme via **CSS** (e.g. with `createStyles` and a `className`), that mapping does not run—you must set both:
+
+1. The **brand token** to your color value.
+2. The **system brand token** to reference the brand token.
+
+Example using numerical brand tokens and system tokens:
+
+```tsx
+import { createStyles } from '@workday/canvas-kit-styling';
+import { brand, system } from '@workday/canvas-tokens-web';
+
+const v4TokensCustomStyles = createStyles({
+  [brand.primary600]: 'darkorange',
+  [system.color.brand.accent.primary]: brand.primary600,
+});
+
+<CanvasProvider className={v4TokensCustomStyles}>
+  <App />
+</CanvasProvider>
+```
+
+In plain CSS you would set the brand variable and set the system variable to reference it (e.g. `var(--cnvs-brand-primary-600)`).
+
 ### Theming Modals and Dialogs
 
 Previously, the `usePopupStack` hook created a CSS class name that was passed to our Popups. We attached those theme styles to that class name. This allowed the theme to be available in our Popups. But it also created a cascade barrier that blocked the global theme from being applied to our Popup components.
diff --git a/modules/react/popup/lib/hooks/usePopupStack.ts b/modules/react/popup/lib/hooks/usePopupStack.ts
index ba2c03e300..19c477dc99 100644
--- a/modules/react/popup/lib/hooks/usePopupStack.ts
+++ b/modules/react/popup/lib/hooks/usePopupStack.ts
@@ -1,12 +1,8 @@
+import {Theme, ThemeContext} from '@emotion/react';
 import React from 'react';
 
 import {PopupStack} from '@workday/canvas-kit-popup-stack';
-import {
-  isElementRTL,
-  useCanvasThemeToCssVars,
-  useLocalRef,
-  useTheme,
-} from '@workday/canvas-kit-react/common';
+import {isElementRTL, useCanvasThemeToCssVars, useLocalRef} from '@workday/canvas-kit-react/common';
 
 /**
  * **Note:** If you're using {@link Popper}, you do not need to use this hook directly.
@@ -55,10 +51,9 @@ export const usePopupStack = <E extends HTMLElement>(
   target?: HTMLElement | React.RefObject<HTMLElement>
 ): React.RefObject<HTMLElement> => {
   const {elementRef, localRef} = useLocalRef(ref);
-  // Use useTheme() (no args) so we get the filled theme from Emotion context—same as CanvasProvider.
-  // Passing raw context can miss filling; useTheme() ensures palette + system.brand tokens are resolved.
-  const filledTheme = useTheme();
-  const {style} = useCanvasThemeToCssVars(filledTheme, {});
+
+  const theme = React.useContext(ThemeContext as React.Context<Theme>);
+  const {style} = useCanvasThemeToCssVars(theme, {});
   const firstLoadRef = React.useRef(true); // React 19 can call a useState more than once, so we need to track if we've already created a container
 
   // useState function input ensures we only create a container once.
diff --git a/modules/react/popup/stories/visual-testing/Popup.stories.tsx b/modules/react/popup/stories/visual-testing/Popup.stories.tsx
index 17b1a8320e..e6a2b15a2e 100644
--- a/modules/react/popup/stories/visual-testing/Popup.stories.tsx
+++ b/modules/react/popup/stories/visual-testing/Popup.stories.tsx
@@ -170,8 +170,8 @@ export const PopupThemed = {
     });
     return (
       <CanvasProvider theme={{canvas: {palette: {primary: {main: base.magenta600}}}}}>
-        <PrimaryButton>Primary Button</PrimaryButton>
         <Popup model={model}>
+          <Popup.Target as={PrimaryButton}>Primary Button</Popup.Target>
           <Popup.Popper>
             <Popup.Card style={{animation: 'none'}} width={300}>
               <Popup.CloseIcon aria-label="" />

From bde1e3edeb45a1a73aef068d43067342560780e7 Mon Sep 17 00:00:00 2001
From: "manuel.carrera" <manuel.carrera@workday.com>
Date: Tue, 24 Feb 2026 13:26:19 -0700
Subject: [PATCH 05/12] fix: Clean up theming docs

---
 .../llm/upgrade-guides/15.0-UPGRADE-GUIDE.md  |  32 +++
 modules/react/common/stories/mdx/Theming.mdx  | 198 ++++--------------
 2 files changed, 69 insertions(+), 161 deletions(-)

diff --git a/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md b/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md
index 5be87e2d2f..39df39d6f2 100644
--- a/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md
+++ b/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md
@@ -30,6 +30,8 @@ space tokens, the new tokens aim to add more semantic meaning to allow for bette
   - [Information Highlight ⚡️](#information-highlight-️)
 - [Component Updates](#component-updates)
   - [Buttons](#buttons)
+- [Theming](#theming)
+  - [System Brand Tokens and Brand Tokens](#system-brand-tokens-and-brand-tokens)
 - [Deprecations](#deprecations)
   - [Accent Icon](#accent-icon)
   - [Applet Icon](#applet-icon)
@@ -391,6 +393,36 @@ tokens. These changes are **only visual**.
 `PrimaryButton`, `SecondaryButton`, `DeleteButton`, `TertiaryButton`, `ToolbarButton`,
 `ToolbarDropdownButton`, `Hyperlink`, `ExternalHyperlink`, and `ActionBar`.
 
+## Theming
+
+### System Brand Tokens and Brand Tokens
+
+The relationship between **system brand tokens** (e.g. `system.color.brand.accent.primary`) and **brand tokens** (e.g. `brand.primary600`) has changed. Teams can still set palette values such as `base`, `dark`, `darkest`, `light`, `lightest`, and `lighter` via the `CanvasProvider` theme prop. The mapping inside `CanvasProvider` exists for **backwards compatibility**: when you pass a theme object, we forward those values to both the legacy brand tokens and the system brand tokens so existing usage continues to work.
+
+If you theme via **CSS** (e.g. with `createStyles` and a `className` on `CanvasProvider`), that automatic mapping does not run. You must:
+
+1. **Set the brand token** to your desired color value.
+2. **Set the system brand token** to reference the brand token (so components that use system tokens still pick up your theme).
+
+Example:
+
+```tsx
+import { createStyles } from '@workday/canvas-kit-styling';
+import { brand, system } from '@workday/canvas-tokens-web';
+
+const v4TokensCustomStyles = createStyles({
+  [brand.primary600]: 'darkorange',
+  [system.color.brand.accent.primary]: brand.primary600,
+});
+
+// Apply the class to CanvasProvider (or a scoped container)
+<CanvasProvider className={v4TokensCustomStyles}>
+  <App />
+</CanvasProvider>
+```
+
+Here the **class name** defines the value for the brand token (`brand.primary600`) and sets the system brand token (`system.color.brand.accent.primary`) to that brand token so both the semantic brand layer and the system layer stay in sync. In plain CSS you would do the same: define the brand variable and set the system variable to `var(--cnvs-brand-primary-600)` (or the appropriate token name).
+
 ## Deprecations
 
 We add the [@deprecated](https://jsdoc.app/tags-deprecated.html) JSDoc tag to code we plan to remove
diff --git a/modules/react/common/stories/mdx/Theming.mdx b/modules/react/common/stories/mdx/Theming.mdx
index e0dbb8a047..d790850a35 100644
--- a/modules/react/common/stories/mdx/Theming.mdx
+++ b/modules/react/common/stories/mdx/Theming.mdx
@@ -9,7 +9,7 @@ import {Theming} from './examples/Theming';
 
 ## Overview
 
-Canvas Kit v14 introduces a significant shift in our approach to theming: we've moved away from
+Canvas Kit v14 and v15 introduces a significant shift in our approach to theming: we've moved away from
 JavaScript-based theme objects to CSS variables. This change provides better performance, improved
 developer experience, and greater flexibility for theming applications.
 
@@ -20,6 +20,8 @@ developer experience, and greater flexibility for theming applications.
 >
 > If your application renders within an environment that already imports these CSS variables, **do not re-import them**.
 
+View our latest tokens documentation [here](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).
+
 ## Migration from v10 Theme Prop to v14 CSS Variables
 
 ### The Evolution
@@ -80,11 +82,11 @@ and scoped to the `div` that the `CanvasProvider` created. This meant that anyth
 or outside of the `CanvasProvider` would not be able to cascade down to the components within the
 `CanvasProvider`.
 
-If you provide a `theme` to the `CanvasProvider`, it will create a scoped theme. Note that in v14, global CSS variables are the recommended way to theme Popups and Modals consistently.
+If you provide a `theme` to the `CanvasProvider`, it will create a scoped theme. Note that in v14 and v15, global CSS variables are the recommended way to theme Popups and Modals consistently.
 
 ## Global vs Scoped Theming
 
-Canvas Kit v14 supports two theming strategies: **global theming** and **scoped theming**. Understanding the difference is important to avoid unexpected behavior.
+Canvas Kit v14 and v15 supports two theming strategies: **global theming** and **scoped theming**. Understanding the difference is important to avoid unexpected behavior.
 
 ### Global Theming
 
@@ -94,16 +96,16 @@ Global theming applies CSS variables at the `:root` level, making them available
 @import '@workday/canvas-tokens-web/css/base/_variables.css';
 :root {
 	// This is showing how you can change the value of a token at the root level of your application.
-  --cnvs-brand-primary-base: var(--cnvs-base-palette-magenta-600);
+  --cnvs-brand-primary-600: var(--cnvs-base-palette-magenta-600);
 }
 ```
 
 ### Scoped Theming
 
-Scoped theming applies CSS variables to a specific section of your application using the `CanvasProvider` with either a `className` or `theme` prop. The theme only affects components within that provider.
+Scoped theming applies CSS variables to a specific section of your application using the `CanvasProvider` via the `theme` prop. The theme only affects components within that provider.
 
 ```tsx
-// Using the theme prop for scoped theming. This will set the [brand.primary.**] tokens to shades of purple.
+// Using the theme prop for scoped theming. This will set the [brand.primary.**] tokens to shades of purple. This will also ensure that the Popup and Modal components are themed consistently.
 <CanvasProvider theme={{canvas: {palette: {primary: {main: 'purple'}}}}}>
   <ScopedSection />
 </CanvasProvider>
@@ -123,7 +125,7 @@ For all other cases, use global theming at `:root` to ensure consistent theming
 
 ## ✅ Preferred Approach (v14+)
 
-Canvas Kit v14 promotes using CSS variables for theming, which can be applied in two ways:
+Canvas Kit v14 and v15 promotes using CSS variables for theming, which can be applied in two ways:
 
 ### Method 1: Global CSS Variables (Recommended)
 
@@ -138,13 +140,12 @@ CSS:
 
 :root {
   /* Override brand primary colors */
-  --cnvs-brand-primary-base: var(--cnvs-base-palette-magenta-600);
-  --cnvs-brand-primary-light: var(--cnvs-base-palette-magenta-200);
-  --cnvs-brand-primary-lighter: var(--cnvs-base-palette-magenta-50);
-  --cnvs-brand-primary-lightest: var(--cnvs-base-palette-magenta-25);
-  --cnvs-brand-primary-dark: var(--cnvs-base-palette-magenta-700);
-  --cnvs-brand-primary-darkest: var(--cnvs-base-palette-magenta-800);
-  --cnvs-brand-primary-accent: var(--cnvs-base-palette-neutral-0);
+  --cnvs-brand-primary-600: var(--cnvs-base-palette-magenta-600);
+  --cnvs-brand-primary-200: var(--cnvs-base-palette-magenta-200);
+  --cnvs-brand-primary-50: var(--cnvs-base-palette-magenta-50);
+  --cnvs-brand-primary-25: var(--cnvs-base-palette-magenta-25);
+  --cnvs-brand-primary-700: var(--cnvs-base-palette-magenta-700);
+  --cnvs-brand-primary-800: var(--cnvs-base-palette-magenta-800);
 }
 ```
 
@@ -154,90 +155,18 @@ CSS:
 
 ### Method 2: Provider-Level CSS Variables
 
-Use Canvas Kit's `createStyles` utility to generate themed class names that can be applied to
+Use Canvas Kit's `CanvasProvider` and `theme` prop to generate themed class names that can be applied to
 specific components or sections:
 
-> **Note:** Doing the following **will create a cascade barrier**. Only use this method if you
-> intentionally want to override the default theme.
 
 ```tsx
-import {createStyles}from "@workday/canvas-kit-styling"
-import {brand, base} from "@workday/canvas-tokens-web"
 import {CanvasProvider} from "@workday/canvas-kit-react/common"
-
-// You can import the CSS variables in a ts file or an index.css file. You do not need to do both.
-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';
-
-// Generate a class name that defines CSS variables
-const themedBrand = createStyles({
-  [brand.primary.accent]: base.neutral0,
-  [brand.primary.darkest]: base.blue800,
-  [brand.primary.dark]: base.blue700,
-  [brand.primary.base]: base.blue600,
-  [brand.primary.light]: base.blue200,
-  [brand.primary.lighter]: base.blue50,
-  [brand.primary.lightest]: base.blue25,
-})
-
-<CanvasProvider className={themedBrand}>
+// This will set the [brand.primary.**] tokens to shades of purple. This will also ensure that the Popup and Modal components are themed consistently.
+<CanvasProvider theme={{canvas: {palette: {primary: {main: 'purple'}}}}}>
   <App/>
 </CanvasProvider>
 ```
 
-#### System Brand Tokens When Theming via CSS
-
-Components use **system brand tokens** (e.g. `system.color.brand.accent.primary`) for colors. Those system tokens reference **brand tokens** (e.g. `brand.primary600`). When you use the `theme` prop on `CanvasProvider`, we map your palette values to both brand and system tokens for backwards compatibility. When you theme via **CSS** (e.g. with `createStyles` and a `className`), that mapping does not run—you must set both:
-
-1. The **brand token** to your color value.
-2. The **system brand token** to reference the brand token.
-
-Example using numerical brand tokens and system tokens:
-
-```tsx
-import { createStyles } from '@workday/canvas-kit-styling';
-import { brand, system } from '@workday/canvas-tokens-web';
-
-const v4TokensCustomStyles = createStyles({
-  [brand.primary600]: 'darkorange',
-  [system.color.brand.accent.primary]: brand.primary600,
-});
-
-<CanvasProvider className={v4TokensCustomStyles}>
-  <App />
-</CanvasProvider>
-```
-
-In plain CSS you would set the brand variable and set the system variable to reference it (e.g. `var(--cnvs-brand-primary-600)`).
-
-### Theming Modals and Dialogs
-
-Previously, the `usePopupStack` hook created a CSS class name that was passed to our Popups. We attached those theme styles to that class name. This allowed the theme to be available in our Popups. But it also created a cascade barrier that blocked the global theme from being applied to our Popup components.
-Because we now use global CSS variables, we no longer need this class name to provide the global theme to Popups. But we have to remove this generated class name to allow the global theme to be applied to Popups.
-
-**Before in v13**
-
-```tsx
-// When passing a theme to the Canvas Provider, the `usePopupStack` would grab the theme and generate a class to forward the theme to Modals and Dialogs. This would create a cascade barrier for any CSS variables defined at the root.
-<CanvasProvider theme={{canvas: {palette: {primary: {main: 'blue'}}}}}>
-  <Modal>//... rest of modal code</Modal>
-</CanvasProvider>
-```
-
-**After in v14**
-
-```tsx
-// If you wish to still theme you application and Modals, you can either define the CSS variables at the root level of your application or define a className and pass it to the CanvasProvider.
-:root {
- --cnvs-brand-primary-base: blue;
-}
-
-<CanvasProvider>
-  <Modal>//... rest of modal code</Modal>
-</CanvasProvider>
-```
-
 ## CSS Token Structure
 
 Canvas Kit provides three layers of CSS variables.
@@ -258,10 +187,12 @@ Base tokens define foundation palette and design values.
 Brand tokens define semantic color assignments.
 
 ```css
---cnvs-brand-primary-base: var(--cnvs-base-palette-blue-600);
---cnvs-brand-primary-accent: var(--cnvs-base-palette-neutral-0);
---cnvs-brand-error-base: var(--cnvs-base-palette-red-600);
---cnvs-brand-success-base: var(--cnvs-base-palette-green-600);
+--cnvs-brand-primary-600: var(--cnvs-base-palette-blue-600);
+--cnvs-brand-primary-200: var(--cnvs-base-palette-blue-200);
+--cnvs-brand-primary-50: var(--cnvs-base-palette-blue-50);
+--cnvs-brand-primary-25: var(--cnvs-base-palette-blue-25);
+--cnvs-brand-primary-700: var(--cnvs-base-palette-blue-700);
+--cnvs-brand-primary-800: var(--cnvs-base-palette-blue-800);
 ```
 
 ### System Tokens (`system/_variables.css`)
@@ -269,9 +200,8 @@ Brand tokens define semantic color assignments.
 System tokens define component-specific values.
 
 ```css
---cnvs-sys-color-bg-primary-default: var(--cnvs-base-palette-blue-600);
---cnvs-sys-color-text-primary-default: var(--cnvs-base-palette-blue-600);
---cnvs-sys-space-x4: calc(var(--cnvs-base-unit) * 4);
+--cnvs-sys-color-bg-default: var(--cnvs-base-palette-blue-600);
+--cnvs-sys-shape-sm: var(--cnvs-base-size-50);
 ```
 
 ## Practical Examples
@@ -286,29 +216,17 @@ System tokens define component-specific values.
 
 :root {
   /* Primary brand colors */
-  --cnvs-brand-primary-base: var(--cnvs-base-palette-magenta-600);
-  --cnvs-brand-primary-light: var(--cnvs-base-palette-magenta-200);
-  --cnvs-brand-primary-lighter: var(--cnvs-base-palette-magenta-50);
-  --cnvs-brand-primary-lightest: var(--cnvs-base-palette-magenta-25);
-  --cnvs-brand-primary-dark: var(--cnvs-base-palette-magenta-700);
-  --cnvs-brand-primary-darkest: var(--cnvs-base-palette-magenta-800);
-  --cnvs-brand-primary-accent: var(--cnvs-base-palette-neutral-0);
+  --cnvs-brand-primary-600: var(--cnvs-base-palette-magenta-600);
+  --cnvs-brand-primary-200: var(--cnvs-base-palette-magenta-200);
+  --cnvs-brand-primary-50: var(--cnvs-base-palette-magenta-50);
+  --cnvs-brand-primary-25: var(--cnvs-base-palette-magenta-25);
+  --cnvs-brand-primary-700: var(--cnvs-base-palette-magenta-700);
+  --cnvs-brand-primary-800: var(--cnvs-base-palette-magenta-800);
 }
 ```
 
 <ExampleCodeBlock code={Theming} />
 
-### Dark Mode Implementation
-
-```css
-/* Dark mode theming */
-[data-theme='dark'] {
-  --cnvs-sys-color-bg-default: var(--cnvs-base-palette-neutral-950);
-  --cnvs-sys-color-text-default: var(--cnvs-base-palette-neutral-50);
-  --cnvs-sys-color-border-container: var(--cnvs-base-palette-slate-700);
-  --cnvs-sys-color-bg-alt-default: var(--cnvs-base-palette-slate-800);
-}
-```
 
 ### RTL Support
 
@@ -435,29 +353,9 @@ const theme = {
 Replace theme-based `CanvasProvider` usage with CSS class-based theming.
 
 ```tsx
-// Before:
-<CanvasProvider theme={customTheme}>
+<CanvasProvider theme={{canvas: {palette: {primary: {main: 'green'}}}}}>
   <App />
 </CanvasProvider>
-
-// After:
-<CanvasProvider className={customThemeClass}>
-  <App />
-</CanvasProvider>
-```
-
-> **Note:** Using a class means you will need to define each property of the palette for full
-> control over theming.
-
-### Step 4: Test Component Rendering
-
-Verify that Canvas Kit components (like `PrimaryButton`) correctly use the new CSS variables.
-
-```tsx
-import {PrimaryButton} from '@workday/canvas-kit-react/button';
-
-// This should automatically use your CSS variable overrides
-<PrimaryButton>Themed Button</PrimaryButton>;
 ```
 
 ## Best Practices
@@ -468,7 +366,7 @@ Use brand tokens instead of base tokens for better maintainability.
 
 ```css
 /* ✅ Good - semantic meaning */
---cnvs-brand-primary-base: var(--cnvs-base-palette-blue-600);
+--cnvs-brand-primary-600: var(--cnvs-base-palette-blue-600);
 
 /* ❌ Avoid - direct base token usage */
 --cnvs-base-palette-blue-600: blue;
@@ -478,13 +376,7 @@ Use brand tokens instead of base tokens for better maintainability.
 
 Ensure color combinations meet accessibility standards.
 
-```css
-/* Verify contrast ratios for text/background combinations */
-:root {
-  --cnvs-brand-primary-base: var(--cnvs-base-palette-blue-600);
-  --cnvs-brand-primary-accent: var(--cnvs-base-palette-neutral-0); /* White text */
-}
-```
+For a full list of color contrast pairs, view our [Color Contrast](https://canvas.workday.com/guidelines/color/color-contrast) documentation.
 
 ### 3. Avoid Component Level Theming
 
@@ -494,15 +386,11 @@ component level.
 ```tsx
 /* ✅ Good - App level theming */
 import {CanvasProvider} from '@workday/canvas-kit-react/common';
-import {createStyles} from '@workday/canvas-kit-styling';
-import {base, brand} from '@workday/canvas-tokens-web';
 
-const myCustomTheme = createStyles({
-  [brand.primary.base]: base.magenta600
-})
+import {base, brand} from '@workday/canvas-tokens-web';
 
 
-<CanvasProvider className={myCustomTheme}>
+<CanvasProvider theme={{canvas: {palette: {primary: {main: base.magenta600}}}}}>
   <App/>
 </CanvasProvider>
 
@@ -520,18 +408,6 @@ const myCustomTheme = createStyles({
 
 ```
 
-## Component Compatibility
-
-All Canvas Kit components in v14 automatically consume CSS variables. No component-level changes are
-required when switching from the theme prop approach to CSS variables.
-
-### Supported Components
-
-- ✅ All Button variants (`PrimaryButton`, `SecondaryButton`, etc.)
-- ✅ Form components (`TextInput`, `FormField`, etc.)
-- ✅ Layout components (`Card`, `Modal`, etc.)
-- ✅ Navigation components (`Tabs`, `SidePanel`, etc.)
-
 ## Performance Benefits
 
 The CSS variable approach provides several performance improvements:

From 02af8f0ac7fbc7972274ae106e8a24ec4bd584ff Mon Sep 17 00:00:00 2001
From: "manuel.carrera" <manuel.carrera@workday.com>
Date: Tue, 24 Feb 2026 13:47:49 -0700
Subject: [PATCH 06/12] fix: Update example

---
 modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx       | 24 ++-----------------
 .../common/stories/mdx/examples/Theming.tsx   | 14 ++---------
 2 files changed, 4 insertions(+), 34 deletions(-)

diff --git a/modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx b/modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx
index 36cbf91aa4..a6c061c9d4 100644
--- a/modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx
+++ b/modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx
@@ -404,30 +404,10 @@ tokens. These changes are **only visual**.
 ### System Brand Tokens and Brand Tokens
 
 The relationship between **system brand tokens** (e.g. `system.color.brand.accent.primary`) and **brand tokens** (e.g. `brand.primary600`) has changed. Teams can still set palette values such as `base`, `dark`, `darkest`, `light`, `lightest`, and `lighter` via the `CanvasProvider` theme prop. The mapping inside `CanvasProvider` exists for **backwards compatibility**: when you pass a theme object, we forward those values to both the legacy brand tokens and the system brand tokens so existing usage continues to work.
+For more information on theming, view our [Theming](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs) documentation.
 
-If you theme via **CSS** (e.g. with `createStyles` and a `className` on `CanvasProvider`), that automatic mapping does not run. You must:
+For more information on our tokens, view our [Tokens](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs) documentation.
 
-1. **Set the brand token** to your desired color value.
-2. **Set the system brand token** to reference the brand token (so components that use system tokens still pick up your theme).
-
-Example:
-
-```tsx
-import { createStyles } from '@workday/canvas-kit-styling';
-import { brand, system } from '@workday/canvas-tokens-web';
-
-const v4TokensCustomStyles = createStyles({
-  [brand.primary600]: 'darkorange',
-  [system.color.brand.accent.primary]: brand.primary600,
-});
-
-// Apply the class to CanvasProvider (or a scoped container)
-<CanvasProvider className={v4TokensCustomStyles}>
-  <App />
-</CanvasProvider>
-```
-
-Here the **class name** defines the value for the brand token (`brand.primary600`) and sets the system brand token (`system.color.brand.accent.primary`) to that brand token so both the semantic brand layer and the system layer stay in sync. In plain CSS you would do the same: define the brand variable and set the system variable to `var(--cnvs-brand-primary-600)` (or the appropriate token name).
 
 ## Deprecations
 
diff --git a/modules/react/common/stories/mdx/examples/Theming.tsx b/modules/react/common/stories/mdx/examples/Theming.tsx
index d756521d8f..a4cc73f346 100644
--- a/modules/react/common/stories/mdx/examples/Theming.tsx
+++ b/modules/react/common/stories/mdx/examples/Theming.tsx
@@ -1,17 +1,7 @@
 import {PrimaryButton} from '@workday/canvas-kit-react/button';
 import {Card} from '@workday/canvas-kit-react/card';
 import {CanvasProvider} from '@workday/canvas-kit-react/common';
-import {createStyles} from '@workday/canvas-kit-styling';
-import {base, brand, system} from '@workday/canvas-tokens-web';
-
-const customTheme = createStyles({
-  [brand.primary.base]: base.green600,
-  [brand.primary.dark]: base.green700,
-  [brand.primary.darkest]: base.green800,
-  [brand.common.focusOutline]: base.green600,
-  [system.color.fg.strong]: base.indigo900,
-  [system.color.border.container]: base.indigo300,
-});
+import {base} from '@workday/canvas-tokens-web';
 
 const App = () => {
   return (
@@ -45,7 +35,7 @@ const App = () => {
 
 export const Theming = () => {
   return (
-    <CanvasProvider className={customTheme}>
+    <CanvasProvider theme={{canvas: {palette: {primary: {main: base.green600}}}}}>
       <App />
     </CanvasProvider>
   );

From 5e1b2ce452c572a70f5881418fb1a5b0a7efe2a8 Mon Sep 17 00:00:00 2001
From: "manuel.carrera" <manuel.carrera@workday.com>
Date: Tue, 24 Feb 2026 13:55:32 -0700
Subject: [PATCH 07/12] fix: Update theming example

---
 .../llm/upgrade-guides/15.0-UPGRADE-GUIDE.md  | 25 ++---------------
 .../common/stories/mdx/examples/Theming.tsx   | 28 +++++++++++++------
 2 files changed, 21 insertions(+), 32 deletions(-)

diff --git a/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md b/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md
index 39df39d6f2..6f89e56ce2 100644
--- a/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md
+++ b/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md
@@ -398,30 +398,9 @@ tokens. These changes are **only visual**.
 ### System Brand Tokens and Brand Tokens
 
 The relationship between **system brand tokens** (e.g. `system.color.brand.accent.primary`) and **brand tokens** (e.g. `brand.primary600`) has changed. Teams can still set palette values such as `base`, `dark`, `darkest`, `light`, `lightest`, and `lighter` via the `CanvasProvider` theme prop. The mapping inside `CanvasProvider` exists for **backwards compatibility**: when you pass a theme object, we forward those values to both the legacy brand tokens and the system brand tokens so existing usage continues to work.
+For more information on theming, view our [Theming](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs) documentation.
 
-If you theme via **CSS** (e.g. with `createStyles` and a `className` on `CanvasProvider`), that automatic mapping does not run. You must:
-
-1. **Set the brand token** to your desired color value.
-2. **Set the system brand token** to reference the brand token (so components that use system tokens still pick up your theme).
-
-Example:
-
-```tsx
-import { createStyles } from '@workday/canvas-kit-styling';
-import { brand, system } from '@workday/canvas-tokens-web';
-
-const v4TokensCustomStyles = createStyles({
-  [brand.primary600]: 'darkorange',
-  [system.color.brand.accent.primary]: brand.primary600,
-});
-
-// Apply the class to CanvasProvider (or a scoped container)
-<CanvasProvider className={v4TokensCustomStyles}>
-  <App />
-</CanvasProvider>
-```
-
-Here the **class name** defines the value for the brand token (`brand.primary600`) and sets the system brand token (`system.color.brand.accent.primary`) to that brand token so both the semantic brand layer and the system layer stay in sync. In plain CSS you would do the same: define the brand variable and set the system variable to `var(--cnvs-brand-primary-600)` (or the appropriate token name).
+For more information on our tokens, view our [Tokens](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs) documentation.
 
 ## Deprecations
 
diff --git a/modules/react/common/stories/mdx/examples/Theming.tsx b/modules/react/common/stories/mdx/examples/Theming.tsx
index a4cc73f346..ff2f8b5a4e 100644
--- a/modules/react/common/stories/mdx/examples/Theming.tsx
+++ b/modules/react/common/stories/mdx/examples/Theming.tsx
@@ -1,6 +1,8 @@
 import {PrimaryButton} from '@workday/canvas-kit-react/button';
 import {Card} from '@workday/canvas-kit-react/card';
 import {CanvasProvider} from '@workday/canvas-kit-react/common';
+import {FormField} from '@workday/canvas-kit-react/form-field';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
 import {base} from '@workday/canvas-tokens-web';
 
 const App = () => {
@@ -11,12 +13,15 @@ const App = () => {
           palette: {
             primary: {
               main: base.green600,
-              dark: base.green700,
-              darkest: base.green800,
-              light: base.green200,
-              lighter: base.green50,
-              lightest: base.green25,
-              contrast: base.neutral0,
+            },
+            alert: {
+              main: base.magenta600,
+            },
+            common: {
+              focusOutline: base.purple500,
+              alertInner: base.magenta400,
+              alertOuter: base.magenta500,
+              errorInner: base.red500,
             },
           },
         },
@@ -26,7 +31,12 @@ const App = () => {
         <Card.Heading>Theming</Card.Heading>
         <Card.Body>
           <PrimaryButton>Theming</PrimaryButton>
-          <input />
+          <FormField error="caution">
+            <FormField.Label>Email</FormField.Label>
+            <FormField.Field>
+              <FormField.Input as={TextInput} />
+            </FormField.Field>
+          </FormField>
         </Card.Body>
       </Card>
     </CanvasProvider>
@@ -35,8 +45,8 @@ const App = () => {
 
 export const Theming = () => {
   return (
-    <CanvasProvider theme={{canvas: {palette: {primary: {main: base.green600}}}}}>
+    <div>
       <App />
-    </CanvasProvider>
+    </div>
   );
 };

From c3a07f05b95bba4d740942978195dc0dfe8dc460 Mon Sep 17 00:00:00 2001
From: "manuel.carrera" <manuel.carrera@workday.com>
Date: Tue, 24 Feb 2026 13:56:55 -0700
Subject: [PATCH 08/12] docs: Update docs

---
 modules/react/common/stories/mdx/Theming.mdx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/modules/react/common/stories/mdx/Theming.mdx b/modules/react/common/stories/mdx/Theming.mdx
index d790850a35..672b6fb8f6 100644
--- a/modules/react/common/stories/mdx/Theming.mdx
+++ b/modules/react/common/stories/mdx/Theming.mdx
@@ -225,6 +225,8 @@ System tokens define component-specific values.
 }
 ```
 
+### Scoped Theming
+
 <ExampleCodeBlock code={Theming} />
 
 

From be198973f1012949afd9668dae664f1f767546c2 Mon Sep 17 00:00:00 2001
From: Manuel Carrera <mannycarrera4@users.noreply.github.com>
Date: Thu, 26 Feb 2026 16:09:03 -0700
Subject: [PATCH 09/12] Update modules/react/common/lib/CanvasProvider.tsx

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 modules/react/common/lib/CanvasProvider.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/modules/react/common/lib/CanvasProvider.tsx b/modules/react/common/lib/CanvasProvider.tsx
index 9455ffa220..7e9f895bc4 100644
--- a/modules/react/common/lib/CanvasProvider.tsx
+++ b/modules/react/common/lib/CanvasProvider.tsx
@@ -61,13 +61,13 @@ const brandColorMapping = {
  * Each token references a brand token that can be overridden through the CanvasProvider theme prop.
  *
  * ### Focus Tokens
- * - `system.color.brand.focus.primary` → `brand.primary.500` → Controlled by `palette.primary.main` or `focusOutline`
+ * - `system.color.brand.focus.primary` → `brand.primary.500` → Controlled by `focusOutline` (separately from `palette.primary.main`, which controls `brand.primary.600`)
  * - `system.color.brand.focus.critical` → `brand.critical.500` → Controlled by `palette.error.dark` or `errorInner`
  * - `system.color.brand.focus.caution.inner` → `brand.caution.400` → Controlled by `palette.alert.main` or `alertInner`
  * - `system.color.brand.focus.caution.outer` → `brand.caution.500` → Controlled by `palette.alert.dark` or `alertOuter`
  *
  * ### Border Tokens
- * - `system.color.brand.border.primary` → `brand.primary.500` → Controlled by `palette.primary.main` or `focusOutline`
+ * - `system.color.brand.border.primary` → `brand.primary.500` → Controlled by `focusOutline` (separately from `palette.primary.main`, which controls `brand.primary.600`)
  * - `system.color.brand.border.critical` → `brand.critical.500` → Controlled by `palette.error.dark` or `errorInner`
  * - `system.color.brand.border.caution` → `brand.caution.500` → Controlled by `palette.alert.dark` or `alertOuter`
  *

From 8a0b228f11340a09ff55fd7826c3ea449801cd56 Mon Sep 17 00:00:00 2001
From: Josh <44883293+josh-bagwell@users.noreply.github.com>
Date: Wed, 4 Mar 2026 13:00:36 -0700
Subject: [PATCH 10/12] chore: Updated docs and JSDocs

---
 modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md | 4 +++-
 modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx               | 4 +++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md b/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md
index 26f889a2dd..9729cc25f0 100644
--- a/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md
+++ b/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md
@@ -46,6 +46,7 @@ semantic meaning to allow for better use and theming.
   - [Navigation](#navigation)
   - [Popups](#popups)
 - [Theming](#theming)
+  - [System Brand Tokens and Brand Tokens](#system-brand-tokens-and-brand-tokens)
 - [Deprecations](#deprecations)
   - [Accent Icon](#accent-icon)
   - [Applet Icon](#applet-icon)
@@ -543,7 +544,8 @@ If you'd like to see the visual differences between `v14` with `v3` tokens and `
 
 ### System Brand Tokens and Brand Tokens
 
-The relationship between **system brand tokens** (e.g. `system.color.brand.accent.primary`) and **brand tokens** (e.g. `brand.primary600`) has changed. Teams can still set palette values such as `base`, `dark`, `darkest`, `light`, `lightest`, and `lighter` via the `CanvasProvider` theme prop. The mapping inside `CanvasProvider` exists for **backwards compatibility**: when you pass a theme object, we forward those values to both the legacy brand tokens and the system brand tokens so existing usage continues to work.
+The relationship between **system brand tokens** (e.g. `system.color.brand.accent.primary`) and **brand tokens** (e.g. `brand.primary600`) has changed. Teams can still set palette values such as `base`, `light`, `lighter`, lightest`, `dark` and `darkest` via the `CanvasProvider` theme prop. The mapping inside `CanvasProvider` exists for **backwards compatibility**. When you pass a theme object, we forward those values to both the legacy brand tokens and the system brand tokens so current implementations will continue to work.
+
 For more information on theming, view our [Theming](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs) documentation.
 
 For more information on our tokens, view our [Tokens](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs) documentation.
diff --git a/modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx b/modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx
index 319e8b91e0..f9e9bdab23 100644
--- a/modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx
+++ b/modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx
@@ -50,6 +50,7 @@ semantic meaning to allow for better use and theming.
   - [Navigation](#navigation)
   - [Popups](#popups)
 - [Theming](#theming)
+  - [System Brand Tokens and Brand Tokens](#system-brand-tokens-and-brand-tokens)
 - [Deprecations](#deprecations)
   - [Accent Icon](#accent-icon)
   - [Applet Icon](#applet-icon)
@@ -550,7 +551,8 @@ If you'd like to see the visual differences between `v14` with `v3` tokens and `
 
 ### System Brand Tokens and Brand Tokens
 
-The relationship between **system brand tokens** (e.g. `system.color.brand.accent.primary`) and **brand tokens** (e.g. `brand.primary600`) has changed. Teams can still set palette values such as `base`, `dark`, `darkest`, `light`, `lightest`, and `lighter` via the `CanvasProvider` theme prop. The mapping inside `CanvasProvider` exists for **backwards compatibility**: when you pass a theme object, we forward those values to both the legacy brand tokens and the system brand tokens so existing usage continues to work.
+The relationship between **system brand tokens** (e.g. `system.color.brand.accent.primary`) and **brand tokens** (e.g. `brand.primary600`) has changed. Teams can still set palette values such as `base`, `light`, `lighter`, lightest`, `dark` and `darkest` via the `CanvasProvider` theme prop. The mapping inside `CanvasProvider` exists for **backwards compatibility**. When you pass a theme object, we forward those values to both the legacy brand tokens and the system brand tokens so current implementations will continue to work.
+
 For more information on theming, view our [Theming](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs) documentation.
 
 For more information on our tokens, view our [Tokens](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs) documentation.

From d0a3db259eb85c78a14c0635c83a503c093ab135 Mon Sep 17 00:00:00 2001
From: "josh.bagwell" <josh.bagwell@workday.com>
Date: Wed, 4 Mar 2026 16:56:58 -0700
Subject: [PATCH 11/12] chore: Updated docs

---
 .../llm/upgrade-guides/15.0-UPGRADE-GUIDE.md  | 137 ++++++++++--------
 modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx       |  12 +-
 modules/react/common/lib/CanvasProvider.tsx   |   7 +-
 3 files changed, 92 insertions(+), 64 deletions(-)

diff --git a/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md b/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md
index 9729cc25f0..92a663718b 100644
--- a/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md
+++ b/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md
@@ -19,17 +19,17 @@ semantic meaning to allow for better use and theming.
   - [Instructions](#instructions)
 - [Component Promotions](#component-promotions)
   - [Avatar](#avatar)
-	- [Structure Changes](#structure-changes)
-	- [API Differences](#api-differences)
-	- [Size Mapping](#api-differences)
-	- [Code Migration](#code-migration)
+  - [Structure Changes](#structure-changes)
+  - [API Differences](#api-differences)
+  - [Size Mapping](#api-differences)
+  - [Code Migration](#code-migration)
   - [Pill](#pill)
   - [Information Highlight](#information-highlight-)
   - [Side Panel](#side-panel)
     - [Migrating from Preview](#migrating-from-preview)
     - [Hook API Changes](#hook-api-changes)
     - [Component API Changes](#component-api-changes)
-	- [Code Migration](#code-migration)
+  - [Code Migration](#code-migration)
   - [Segmented Control](#segmented-control)
     - [API Differences](#api-differences)
     - [Structure Changes](#structure-changes)
@@ -39,7 +39,6 @@ semantic meaning to allow for better use and theming.
   - [Information Highlight](#information-highlight-)
 - [Component Updates](#component-updates)
   - [Buttons](#buttons)
-  - [System Brand Tokens and Brand Tokens](#system-brand-tokens-and-brand-tokens)
   - [Inputs](#inputs)
   - [Containers](#containers)
   - [Indicators](#indicators)
@@ -52,7 +51,7 @@ semantic meaning to allow for better use and theming.
   - [Applet Icon](#applet-icon)
 - [Removals](#removals)
   - [Avatar (Deprecated)](#avatar-deprecated)
-	- [Side Panel (Deprecated)](#side-panel-deprecated)
+  - [Side Panel (Deprecated)](#side-panel-deprecated)
   - [Segmented Control (Deprecated)](#segmented-control-deprecated)
   - [Select (Deprecated)](#select-deprecated)
   - [Search Form (Labs)](#search-form-labs)
@@ -99,9 +98,10 @@ our team. We'd be very happy to walk you through the process to set you up for s
 
 ### Instructions
 
-The easiest way to run our codemod is to use `npx` in your terminal.```sh
-npx @workday/canvas-kit-codemod v15 [path]
-```
+The easiest way to run our codemod is to use `npx` in your terminal.```sh npx
+@workday/canvas-kit-codemod v15 [path]
+
+````
 
 Be sure to provide specific directories that need to be updated via the `[path]` argument. This
 decreases the amount of AST the codemod needs to traverse and reduces the chances of the script
@@ -117,7 +117,7 @@ finished.
 yarn add @workday/canvas-kit-codemod --dev
 yarn canvas-kit-codemod v15 [path]
 yarn remove @workday/canvas-kit-codemod
-```
+````
 
 > **Note:** The codemod only works on `.js`, `.jsx`, `.ts`, and `.tsx` files. You'll need to
 > manually edit other file types (`.json`, `.mdx`, `.md`, etc.). You may need to run your linter
@@ -240,8 +240,7 @@ The promoted `Avatar` includes several new features:
 **PR** [#3634](https://github.com/Workday/canvas-kit/pull/3634)
 
 We've promoted `Pill` from [Preview](#preview) to [Main](#main). There are no changes to the
-functionality of the component. The only change required is updating the import
-statement.
+functionality of the component. The only change required is updating the import statement.
 
 **Before in v14**
 
@@ -261,18 +260,19 @@ import {Pill} from '@workday/canvas-kit-react/pill';
 
 **PR:** [#3670](https://github.com/Workday/canvas-kit/pull/3670)
 
-We've promoted `SidePanel` from [Labs](#labs) to [Main](#main). This replaces the deprecated `SidePanel` that was previously in Main and should replace the one in [Preview](#preview) as well.
+We've promoted `SidePanel` from [Labs](#labs) to [Main](#main). This replaces the deprecated
+`SidePanel` that was previously in Main and should replace the one in [Preview](#preview) as well.
 
 **Before in v14**
 
 ```tsx
-import { SidePanel } from "@workday/canvas-kit-labs-react/side-panel";
+import {SidePanel} from '@workday/canvas-kit-labs-react/side-panel';
 ```
 
 **After in v15**
 
 ```tsx
-import { SidePanel } from "@workday/canvas-kit-react/side-panel";
+import {SidePanel} from '@workday/canvas-kit-react/side-panel';
 ```
 
 > 🤖 The codemod will handle the change of imports as shown above.
@@ -304,15 +304,15 @@ import {SidePanel, useSidePanelModel} from '@workday/canvas-kit-react/side-panel
 
 #### Component API Changes
 
-| Preview                                        | Main                                              |
-| ---------------------------------------------- | ------------------------------------------------- |
-| `<SidePanel {...panelProps}>`                  | `<SidePanel model={model}>` or just `<SidePanel>` |
-| `<SidePanel.ToggleButton {...controlProps} />` | `<SidePanel.ToggleButton />`                      |
-| `<Heading {...labelProps}>`                    | `<SidePanel.Heading>Panel Title</SidePanel.Heading>`              |
-| `expanded` prop on SidePanel                   | Managed by model's `transitionState`              |
-| `touched` prop on SidePanel                    | Managed internally                                |
-| `onExpandedChange` callback                    | Use `onStateTransition` and derive expanded state |
-| `onStateTransition` on component               | `onStateTransition` in model config               |
+| Preview                                        | Main                                                 |
+| ---------------------------------------------- | ---------------------------------------------------- |
+| `<SidePanel {...panelProps}>`                  | `<SidePanel model={model}>` or just `<SidePanel>`    |
+| `<SidePanel.ToggleButton {...controlProps} />` | `<SidePanel.ToggleButton />`                         |
+| `<Heading {...labelProps}>`                    | `<SidePanel.Heading>Panel Title</SidePanel.Heading>` |
+| `expanded` prop on SidePanel                   | Managed by model's `transitionState`                 |
+| `touched` prop on SidePanel                    | Managed internally                                   |
+| `onExpandedChange` callback                    | Use `onStateTransition` and derive expanded state    |
+| `onStateTransition` on component               | `onStateTransition` in model config                  |
 
 #### Code Migration Example
 
@@ -480,7 +480,8 @@ The promoted `SegmentedControl` includes several new features:
 **PR:** [#3633](https://github.com/Workday/canvas-kit/pull/3633)
 
 We've promoted `InformationHighlight` from [Preview](#preview) to [Main](#main). There are no
-changes to the functionality or styling of the component. The only change required is updating the import statement.
+changes to the functionality or styling of the component. The only change required is updating the
+import statement.
 
 **Before in v14**
 
@@ -501,7 +502,8 @@ import {InformationHighlight} from '@workday/canvas-kit-react/information-highli
 The Following components have been updated to use our new `size`, `padding`, `gap` and `shape`
 tokens. These changes are **only visual**.
 
-If you'd like to see the visual differences between `v14` with `v3` tokens and `v15 alpha` with `v4` tokens, check out our [Visual Changes](/docs/guides-upgrade-guides-v15-0-visual-changes--docs) file.
+If you'd like to see the visual differences between `v14` with `v3` tokens and `v15 alpha` with `v4`
+tokens, check out our [Visual Changes](/docs/guides-upgrade-guides-v15-0-visual-changes--docs) file.
 
 ### Buttons
 
@@ -514,7 +516,8 @@ If you'd like to see the visual differences between `v14` with `v3` tokens and `
 
 **PR:** [#3719](https://github.com/Workday/canvas-kit/pull/3719)
 
-`ColorPicker`, `MultiSelect`, `Radio`, `Checkbox`, `FormField`, `Select`, `Switch`, `TextArea` and `TextInput`
+`ColorPicker`, `MultiSelect`, `Radio`, `Checkbox`, `FormField`, `Select`, `Switch`, `TextArea` and
+`TextInput`
 
 ### Containers
 
@@ -526,7 +529,8 @@ If you'd like to see the visual differences between `v14` with `v3` tokens and `
 
 **PR:** [#3738](https://github.com/Workday/canvas-kit/pull/3738)
 
-`StatusIndicator (Preview)`, `Avatar`, `Badge`, `Banner`, `InformationHighlight`, `Pill` and `Skeleton`
+`StatusIndicator (Preview)`, `Avatar`, `Badge`, `Banner`, `InformationHighlight`, `Pill` and
+`Skeleton`
 
 ### Navigation
 
@@ -544,11 +548,21 @@ If you'd like to see the visual differences between `v14` with `v3` tokens and `
 
 ### System Brand Tokens and Brand Tokens
 
-The relationship between **system brand tokens** (e.g. `system.color.brand.accent.primary`) and **brand tokens** (e.g. `brand.primary600`) has changed. Teams can still set palette values such as `base`, `light`, `lighter`, lightest`, `dark` and `darkest` via the `CanvasProvider` theme prop. The mapping inside `CanvasProvider` exists for **backwards compatibility**. When you pass a theme object, we forward those values to both the legacy brand tokens and the system brand tokens so current implementations will continue to work.
+The relationship between **system brand tokens** (e.g. `system.color.brand.accent.primary`) and
+**brand tokens** (e.g. `brand.primary600`) has changed. Teams can still set palette values such as
+`base`, `light`, `lighter`,
+lightest`, `dark`and`darkest`via the`CanvasProvider`theme prop. The mapping inside`CanvasProvider`
+exists for **backwards compatibility**. When you pass a theme object, we forward those values to
+both the legacy brand tokens and the system brand tokens so current implementations will continue to
+work.
 
-For more information on theming, view our [Theming](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs) documentation.
+For more information on theming, view our
+[Theming](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs)
+documentation.
 
-For more information on our tokens, view our [Tokens](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs) documentation.
+For more information on our tokens, view our
+[Tokens](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs)
+documentation.
 
 ## Deprecations
 
@@ -560,15 +574,16 @@ deprecated code is removed.
 
 **PR:** [#3727](https://github.com/Workday/canvas-kit/pull/3727)
 
-The Accent Icon set has been **deprecated** and will be removed in a future major version.
-We recommend migrating to **Expressive Icons**, which are more flexible and aligned with our current design direction.
+The Accent Icon set has been **deprecated** and will be removed in a future major version. We
+recommend migrating to **Expressive Icons**, which are more flexible and aligned with our current
+design direction.
 
 ### Applet Icon
 
 **PR:** [#3727](https://github.com/Workday/canvas-kit/pull/3727)
 
-The Applet Icon set has been **deprecated** and will be removed in a future major version.
-Please migrate to **Expressive Icons**, as Applet Icons will no longer receive updates or support.
+The Applet Icon set has been **deprecated** and will be removed in a future major version. Please
+migrate to **Expressive Icons**, as Applet Icons will no longer receive updates or support.
 
 ## Removals
 
@@ -576,9 +591,9 @@ Please migrate to **Expressive Icons**, as Applet Icons will no longer receive u
 
 **PR:** [#3660](https://github.com/Workday/canvas-kit/pull/3660)
 
-The deprecated `Avatar` that was previously in `@workday/canvas-kit-react/avatar`
-has been removed. This was the older implementation that showed a user icon placeholder
-and supported `light`/`dark` variants.
+The deprecated `Avatar` that was previously in `@workday/canvas-kit-react/avatar` has been removed.
+This was the older implementation that showed a user icon placeholder and supported `light`/`dark`
+variants.
 
 Please migrate to the new `Avatar` component (promoted from Preview) which uses initials display,
 color variants (`blue`, `amber`, `teal`, `purple`), and supports compound components. See the
@@ -588,19 +603,20 @@ color variants (`blue`, `amber`, `teal`, `purple`), and supports compound compon
 
 **PR:** [#3670](https://github.com/Workday/canvas-kit/pull/3670)
 
-The deprecated `SidePanel` that was previously in `@workday/canvas-kit-react/side-panel`
-has been removed. This was the older implementation that used our old patterns.
+The deprecated `SidePanel` that was previously in `@workday/canvas-kit-react/side-panel` has been
+removed. This was the older implementation that used our old patterns.
 
-Please migrate to the new `SidePanel` component (promoted from Labs) which uses a compound
-component pattern and `useSidePanelModel`. See the
-[API Differences](#api-differences) section above for migration guidance.
+Please migrate to the new `SidePanel` component (promoted from Labs) which uses a compound component
+pattern and `useSidePanelModel`. See the [API Differences](#api-differences) section above for
+migration guidance.
 
 ### Segmented Control (Deprecated)
 
 **PR:** [#3626](https://github.com/Workday/canvas-kit/pull/3626)
 
-The deprecated `SegmentedControl` that was previously in `@workday/canvas-kit-react/segmented-control`
-has been removed. This was the older implementation that used `SegmentedControl.Button` subcomponents.
+The deprecated `SegmentedControl` that was previously in
+`@workday/canvas-kit-react/segmented-control` has been removed. This was the older implementation
+that used `SegmentedControl.Button` subcomponents.
 
 Please migrate to the new `SegmentedControl` component (promoted from Preview) which uses a compound
 component pattern with `SegmentedControl.List` and `SegmentedControl.Item`. See the
@@ -677,14 +693,14 @@ import {Select} from '@workday/canvas-kit-react/select';
 const items = ['Small', 'Medium', 'Large'];
 
 <Select items={items}>
-	<FormField label="Size">
-		<FormField.Input as={Select.Input} onChange={(e) => console.log("Selected:", e.target.value)} />
-		<Select.Popper>
-			<Select.Card>
-				<Select.List>{(item) => <Select.Item>{item}</Select.Item>}</Select.List>
-			</Select.Card>
-		</Select.Popper>
-	</FormField>
+  <FormField label="Size">
+    <FormField.Input as={Select.Input} onChange={e => console.log('Selected:', e.target.value)} />
+    <Select.Popper>
+      <Select.Card>
+        <Select.List>{item => <Select.Item>{item}</Select.Item>}</Select.List>
+      </Select.Card>
+    </Select.Popper>
+  </FormField>
 </Select>;
 ```
 
@@ -784,8 +800,8 @@ things you'll want to keep in mind.
   dependencies on your own.
   - We recommend upgrading dependencies before running the codemod.
   - Always review your `package.json` files to make sure your dependency versions look correct.
-- The codemod will not handle every breaking change in this upgrade. You will likely need to make some manual
-  changes to be compatible. Use our Upgrade Guide as a checklist.
+- The codemod will not handle every breaking change in this upgrade. You will likely need to make
+  some manual changes to be compatible. Use our Upgrade Guide as a checklist.
 - Codemods are not bulletproof.
   - Conduct a thorough PR and QA review of all changes to ensure no regressions were introduced.
   - As a safety precaution, we recommend committing the changes from the codemod as a single
@@ -798,9 +814,10 @@ our team. We'd be very happy to walk you through the process to set you up for s
 
 ### Instructions
 
-The easiest way to run our codemod is to use `npx` in your terminal.```sh
-npx @workday/canvas-kit-codemod v${canvasKitMajorVersionNumber} [path]
-```
+The easiest way to run our codemod is to use `npx` in your terminal.```sh npx
+@workday/canvas-kit-codemod v${canvasKitMajorVersionNumber} [path]
+
+````
 
 Be sure to provide specific directories that need to be updated via the `[path]` argument. This
 decreases the amount of AST the codemod needs to traverse and reduces the chances of the script
@@ -816,7 +833,7 @@ finished.
 yarn add @workday/canvas-kit-codemod --dev
 yarn canvas-kit-codemod v${canvasKitMajorVersionNumber} [path]
 yarn remove @workday/canvas-kit-codemod
-```
+````
 
 > **Note**: The codemod only works on `.js`, `.jsx`, `.ts`, and `.tsx` files. You'll need to
 > manually edit other file types (`.json`, `.mdx`, `.md`, etc.). You may need to run your linter
diff --git a/modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx b/modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx
index f9e9bdab23..c18cc5ee60 100644
--- a/modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx
+++ b/modules/docs/mdx/15.0-UPGRADE-GUIDE.mdx
@@ -43,7 +43,6 @@ semantic meaning to allow for better use and theming.
   - [Information Highlight](#information-highlight-)
 - [Component Updates](#component-updates)
   - [Buttons](#buttons)
-  - [System Brand Tokens and Brand Tokens](#system-brand-tokens-and-brand-tokens)
   - [Inputs](#inputs)
   - [Containers](#containers)
   - [Indicators](#indicators)
@@ -551,11 +550,18 @@ If you'd like to see the visual differences between `v14` with `v3` tokens and `
 
 ### System Brand Tokens and Brand Tokens
 
-The relationship between **system brand tokens** (e.g. `system.color.brand.accent.primary`) and **brand tokens** (e.g. `brand.primary600`) has changed. Teams can still set palette values such as `base`, `light`, `lighter`, lightest`, `dark` and `darkest` via the `CanvasProvider` theme prop. The mapping inside `CanvasProvider` exists for **backwards compatibility**. When you pass a theme object, we forward those values to both the legacy brand tokens and the system brand tokens so current implementations will continue to work.
+The relationship between **system brand tokens** (e.g. `system.color.brand.accent.primary`) and **brand tokens** (e.g. `brand.primary600`) has changed. Teams can still set palette values such as `base`, `light`, `lighter`, `lightest`, `dark` and `darkest` via the `CanvasProvider` `theme` prop. The mapping inside `CanvasProvider` exists for **backwards compatibility**. When you pass a theme object, we forward those values to both the legacy brand tokens and the system brand tokens so current implementations will continue to work.
 
 For more information on theming, view our [Theming](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs) documentation.
 
-For more information on our tokens, view our [Tokens](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs) documentation.
+For more information on our tokens, vie\w our [Tokens](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs) documentation.
+
+```tsx
+// This will set the [brand.primary.**] tokens to shades of purple.
+<CanvasProvider theme={{canvas: {palette: {primary: {main: 'purple'}}}}}>
+  <App />
+</CanvasProvider>
+```
 
 
 ## Deprecations
diff --git a/modules/react/common/lib/CanvasProvider.tsx b/modules/react/common/lib/CanvasProvider.tsx
index 4ddf48b80b..fe77c45324 100644
--- a/modules/react/common/lib/CanvasProvider.tsx
+++ b/modules/react/common/lib/CanvasProvider.tsx
@@ -42,7 +42,12 @@ const numericalTokenMapping = {
 
 /**
  * Mapping from deprecated theme palette colors to new brand token names.
- * For example: 'primary' -> 'primary', 'error' -> 'critical', 'success' -> 'positive'
+ * For example:
+ * `primary` -> `primary`
+ * `error` -> `critical`
+ * `success` -> `positive`
+ * `alert` -> `caution`
+ * `neutral` -> `neutral`
  */
 const brandColorMapping = {
   primary: 'primary',

From 376c71d23ab363df9af8ec07decb128a721c712d Mon Sep 17 00:00:00 2001
From: "josh.bagwell" <josh.bagwell@workday.com>
Date: Wed, 4 Mar 2026 16:58:26 -0700
Subject: [PATCH 12/12] chore: Updated md file

---
 .../llm/upgrade-guides/15.0-UPGRADE-GUIDE.md  | 143 ++++++++----------
 1 file changed, 66 insertions(+), 77 deletions(-)

diff --git a/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md b/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md
index 92a663718b..367edf2f54 100644
--- a/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md
+++ b/modules/docs/llm/upgrade-guides/15.0-UPGRADE-GUIDE.md
@@ -19,17 +19,17 @@ semantic meaning to allow for better use and theming.
   - [Instructions](#instructions)
 - [Component Promotions](#component-promotions)
   - [Avatar](#avatar)
-  - [Structure Changes](#structure-changes)
-  - [API Differences](#api-differences)
-  - [Size Mapping](#api-differences)
-  - [Code Migration](#code-migration)
+	- [Structure Changes](#structure-changes)
+	- [API Differences](#api-differences)
+	- [Size Mapping](#api-differences)
+	- [Code Migration](#code-migration)
   - [Pill](#pill)
   - [Information Highlight](#information-highlight-)
   - [Side Panel](#side-panel)
     - [Migrating from Preview](#migrating-from-preview)
     - [Hook API Changes](#hook-api-changes)
     - [Component API Changes](#component-api-changes)
-  - [Code Migration](#code-migration)
+	- [Code Migration](#code-migration)
   - [Segmented Control](#segmented-control)
     - [API Differences](#api-differences)
     - [Structure Changes](#structure-changes)
@@ -51,7 +51,7 @@ semantic meaning to allow for better use and theming.
   - [Applet Icon](#applet-icon)
 - [Removals](#removals)
   - [Avatar (Deprecated)](#avatar-deprecated)
-  - [Side Panel (Deprecated)](#side-panel-deprecated)
+	- [Side Panel (Deprecated)](#side-panel-deprecated)
   - [Segmented Control (Deprecated)](#segmented-control-deprecated)
   - [Select (Deprecated)](#select-deprecated)
   - [Search Form (Labs)](#search-form-labs)
@@ -98,10 +98,9 @@ our team. We'd be very happy to walk you through the process to set you up for s
 
 ### Instructions
 
-The easiest way to run our codemod is to use `npx` in your terminal.```sh npx
-@workday/canvas-kit-codemod v15 [path]
-
-````
+The easiest way to run our codemod is to use `npx` in your terminal.```sh
+npx @workday/canvas-kit-codemod v15 [path]
+```
 
 Be sure to provide specific directories that need to be updated via the `[path]` argument. This
 decreases the amount of AST the codemod needs to traverse and reduces the chances of the script
@@ -117,7 +116,7 @@ finished.
 yarn add @workday/canvas-kit-codemod --dev
 yarn canvas-kit-codemod v15 [path]
 yarn remove @workday/canvas-kit-codemod
-````
+```
 
 > **Note:** The codemod only works on `.js`, `.jsx`, `.ts`, and `.tsx` files. You'll need to
 > manually edit other file types (`.json`, `.mdx`, `.md`, etc.). You may need to run your linter
@@ -240,7 +239,8 @@ The promoted `Avatar` includes several new features:
 **PR** [#3634](https://github.com/Workday/canvas-kit/pull/3634)
 
 We've promoted `Pill` from [Preview](#preview) to [Main](#main). There are no changes to the
-functionality of the component. The only change required is updating the import statement.
+functionality of the component. The only change required is updating the import
+statement.
 
 **Before in v14**
 
@@ -260,19 +260,18 @@ import {Pill} from '@workday/canvas-kit-react/pill';
 
 **PR:** [#3670](https://github.com/Workday/canvas-kit/pull/3670)
 
-We've promoted `SidePanel` from [Labs](#labs) to [Main](#main). This replaces the deprecated
-`SidePanel` that was previously in Main and should replace the one in [Preview](#preview) as well.
+We've promoted `SidePanel` from [Labs](#labs) to [Main](#main). This replaces the deprecated `SidePanel` that was previously in Main and should replace the one in [Preview](#preview) as well.
 
 **Before in v14**
 
 ```tsx
-import {SidePanel} from '@workday/canvas-kit-labs-react/side-panel';
+import { SidePanel } from "@workday/canvas-kit-labs-react/side-panel";
 ```
 
 **After in v15**
 
 ```tsx
-import {SidePanel} from '@workday/canvas-kit-react/side-panel';
+import { SidePanel } from "@workday/canvas-kit-react/side-panel";
 ```
 
 > 🤖 The codemod will handle the change of imports as shown above.
@@ -304,15 +303,15 @@ import {SidePanel, useSidePanelModel} from '@workday/canvas-kit-react/side-panel
 
 #### Component API Changes
 
-| Preview                                        | Main                                                 |
-| ---------------------------------------------- | ---------------------------------------------------- |
-| `<SidePanel {...panelProps}>`                  | `<SidePanel model={model}>` or just `<SidePanel>`    |
-| `<SidePanel.ToggleButton {...controlProps} />` | `<SidePanel.ToggleButton />`                         |
-| `<Heading {...labelProps}>`                    | `<SidePanel.Heading>Panel Title</SidePanel.Heading>` |
-| `expanded` prop on SidePanel                   | Managed by model's `transitionState`                 |
-| `touched` prop on SidePanel                    | Managed internally                                   |
-| `onExpandedChange` callback                    | Use `onStateTransition` and derive expanded state    |
-| `onStateTransition` on component               | `onStateTransition` in model config                  |
+| Preview                                        | Main                                              |
+| ---------------------------------------------- | ------------------------------------------------- |
+| `<SidePanel {...panelProps}>`                  | `<SidePanel model={model}>` or just `<SidePanel>` |
+| `<SidePanel.ToggleButton {...controlProps} />` | `<SidePanel.ToggleButton />`                      |
+| `<Heading {...labelProps}>`                    | `<SidePanel.Heading>Panel Title</SidePanel.Heading>`              |
+| `expanded` prop on SidePanel                   | Managed by model's `transitionState`              |
+| `touched` prop on SidePanel                    | Managed internally                                |
+| `onExpandedChange` callback                    | Use `onStateTransition` and derive expanded state |
+| `onStateTransition` on component               | `onStateTransition` in model config               |
 
 #### Code Migration Example
 
@@ -480,8 +479,7 @@ The promoted `SegmentedControl` includes several new features:
 **PR:** [#3633](https://github.com/Workday/canvas-kit/pull/3633)
 
 We've promoted `InformationHighlight` from [Preview](#preview) to [Main](#main). There are no
-changes to the functionality or styling of the component. The only change required is updating the
-import statement.
+changes to the functionality or styling of the component. The only change required is updating the import statement.
 
 **Before in v14**
 
@@ -502,8 +500,7 @@ import {InformationHighlight} from '@workday/canvas-kit-react/information-highli
 The Following components have been updated to use our new `size`, `padding`, `gap` and `shape`
 tokens. These changes are **only visual**.
 
-If you'd like to see the visual differences between `v14` with `v3` tokens and `v15 alpha` with `v4`
-tokens, check out our [Visual Changes](/docs/guides-upgrade-guides-v15-0-visual-changes--docs) file.
+If you'd like to see the visual differences between `v14` with `v3` tokens and `v15 alpha` with `v4` tokens, check out our [Visual Changes](/docs/guides-upgrade-guides-v15-0-visual-changes--docs) file.
 
 ### Buttons
 
@@ -516,8 +513,7 @@ tokens, check out our [Visual Changes](/docs/guides-upgrade-guides-v15-0-visual-
 
 **PR:** [#3719](https://github.com/Workday/canvas-kit/pull/3719)
 
-`ColorPicker`, `MultiSelect`, `Radio`, `Checkbox`, `FormField`, `Select`, `Switch`, `TextArea` and
-`TextInput`
+`ColorPicker`, `MultiSelect`, `Radio`, `Checkbox`, `FormField`, `Select`, `Switch`, `TextArea` and `TextInput`
 
 ### Containers
 
@@ -529,8 +525,7 @@ tokens, check out our [Visual Changes](/docs/guides-upgrade-guides-v15-0-visual-
 
 **PR:** [#3738](https://github.com/Workday/canvas-kit/pull/3738)
 
-`StatusIndicator (Preview)`, `Avatar`, `Badge`, `Banner`, `InformationHighlight`, `Pill` and
-`Skeleton`
+`StatusIndicator (Preview)`, `Avatar`, `Badge`, `Banner`, `InformationHighlight`, `Pill` and `Skeleton`
 
 ### Navigation
 
@@ -548,21 +543,18 @@ tokens, check out our [Visual Changes](/docs/guides-upgrade-guides-v15-0-visual-
 
 ### System Brand Tokens and Brand Tokens
 
-The relationship between **system brand tokens** (e.g. `system.color.brand.accent.primary`) and
-**brand tokens** (e.g. `brand.primary600`) has changed. Teams can still set palette values such as
-`base`, `light`, `lighter`,
-lightest`, `dark`and`darkest`via the`CanvasProvider`theme prop. The mapping inside`CanvasProvider`
-exists for **backwards compatibility**. When you pass a theme object, we forward those values to
-both the legacy brand tokens and the system brand tokens so current implementations will continue to
-work.
+The relationship between **system brand tokens** (e.g. `system.color.brand.accent.primary`) and **brand tokens** (e.g. `brand.primary600`) has changed. Teams can still set palette values such as `base`, `light`, `lighter`, `lightest`, `dark` and `darkest` via the `CanvasProvider` `theme` prop. The mapping inside `CanvasProvider` exists for **backwards compatibility**. When you pass a theme object, we forward those values to both the legacy brand tokens and the system brand tokens so current implementations will continue to work.
 
-For more information on theming, view our
-[Theming](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs)
-documentation.
+For more information on theming, view our [Theming](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs) documentation.
 
-For more information on our tokens, view our
-[Tokens](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs)
-documentation.
+For more information on our tokens, vie\w our [Tokens](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs) documentation.
+
+```tsx
+// This will set the [brand.primary.**] tokens to shades of purple.
+<CanvasProvider theme={{canvas: {palette: {primary: {main: 'purple'}}}}}>
+  <App />
+</CanvasProvider>
+```
 
 ## Deprecations
 
@@ -574,16 +566,15 @@ deprecated code is removed.
 
 **PR:** [#3727](https://github.com/Workday/canvas-kit/pull/3727)
 
-The Accent Icon set has been **deprecated** and will be removed in a future major version. We
-recommend migrating to **Expressive Icons**, which are more flexible and aligned with our current
-design direction.
+The Accent Icon set has been **deprecated** and will be removed in a future major version.
+We recommend migrating to **Expressive Icons**, which are more flexible and aligned with our current design direction.
 
 ### Applet Icon
 
 **PR:** [#3727](https://github.com/Workday/canvas-kit/pull/3727)
 
-The Applet Icon set has been **deprecated** and will be removed in a future major version. Please
-migrate to **Expressive Icons**, as Applet Icons will no longer receive updates or support.
+The Applet Icon set has been **deprecated** and will be removed in a future major version.
+Please migrate to **Expressive Icons**, as Applet Icons will no longer receive updates or support.
 
 ## Removals
 
@@ -591,9 +582,9 @@ migrate to **Expressive Icons**, as Applet Icons will no longer receive updates
 
 **PR:** [#3660](https://github.com/Workday/canvas-kit/pull/3660)
 
-The deprecated `Avatar` that was previously in `@workday/canvas-kit-react/avatar` has been removed.
-This was the older implementation that showed a user icon placeholder and supported `light`/`dark`
-variants.
+The deprecated `Avatar` that was previously in `@workday/canvas-kit-react/avatar`
+has been removed. This was the older implementation that showed a user icon placeholder
+and supported `light`/`dark` variants.
 
 Please migrate to the new `Avatar` component (promoted from Preview) which uses initials display,
 color variants (`blue`, `amber`, `teal`, `purple`), and supports compound components. See the
@@ -603,20 +594,19 @@ color variants (`blue`, `amber`, `teal`, `purple`), and supports compound compon
 
 **PR:** [#3670](https://github.com/Workday/canvas-kit/pull/3670)
 
-The deprecated `SidePanel` that was previously in `@workday/canvas-kit-react/side-panel` has been
-removed. This was the older implementation that used our old patterns.
+The deprecated `SidePanel` that was previously in `@workday/canvas-kit-react/side-panel`
+has been removed. This was the older implementation that used our old patterns.
 
-Please migrate to the new `SidePanel` component (promoted from Labs) which uses a compound component
-pattern and `useSidePanelModel`. See the [API Differences](#api-differences) section above for
-migration guidance.
+Please migrate to the new `SidePanel` component (promoted from Labs) which uses a compound
+component pattern and `useSidePanelModel`. See the
+[API Differences](#api-differences) section above for migration guidance.
 
 ### Segmented Control (Deprecated)
 
 **PR:** [#3626](https://github.com/Workday/canvas-kit/pull/3626)
 
-The deprecated `SegmentedControl` that was previously in
-`@workday/canvas-kit-react/segmented-control` has been removed. This was the older implementation
-that used `SegmentedControl.Button` subcomponents.
+The deprecated `SegmentedControl` that was previously in `@workday/canvas-kit-react/segmented-control`
+has been removed. This was the older implementation that used `SegmentedControl.Button` subcomponents.
 
 Please migrate to the new `SegmentedControl` component (promoted from Preview) which uses a compound
 component pattern with `SegmentedControl.List` and `SegmentedControl.Item`. See the
@@ -693,14 +683,14 @@ import {Select} from '@workday/canvas-kit-react/select';
 const items = ['Small', 'Medium', 'Large'];
 
 <Select items={items}>
-  <FormField label="Size">
-    <FormField.Input as={Select.Input} onChange={e => console.log('Selected:', e.target.value)} />
-    <Select.Popper>
-      <Select.Card>
-        <Select.List>{item => <Select.Item>{item}</Select.Item>}</Select.List>
-      </Select.Card>
-    </Select.Popper>
-  </FormField>
+	<FormField label="Size">
+		<FormField.Input as={Select.Input} onChange={(e) => console.log("Selected:", e.target.value)} />
+		<Select.Popper>
+			<Select.Card>
+				<Select.List>{(item) => <Select.Item>{item}</Select.Item>}</Select.List>
+			</Select.Card>
+		</Select.Popper>
+	</FormField>
 </Select>;
 ```
 
@@ -800,8 +790,8 @@ things you'll want to keep in mind.
   dependencies on your own.
   - We recommend upgrading dependencies before running the codemod.
   - Always review your `package.json` files to make sure your dependency versions look correct.
-- The codemod will not handle every breaking change in this upgrade. You will likely need to make
-  some manual changes to be compatible. Use our Upgrade Guide as a checklist.
+- The codemod will not handle every breaking change in this upgrade. You will likely need to make some manual
+  changes to be compatible. Use our Upgrade Guide as a checklist.
 - Codemods are not bulletproof.
   - Conduct a thorough PR and QA review of all changes to ensure no regressions were introduced.
   - As a safety precaution, we recommend committing the changes from the codemod as a single
@@ -814,10 +804,9 @@ our team. We'd be very happy to walk you through the process to set you up for s
 
 ### Instructions
 
-The easiest way to run our codemod is to use `npx` in your terminal.```sh npx
-@workday/canvas-kit-codemod v${canvasKitMajorVersionNumber} [path]
-
-````
+The easiest way to run our codemod is to use `npx` in your terminal.```sh
+npx @workday/canvas-kit-codemod v${canvasKitMajorVersionNumber} [path]
+```
 
 Be sure to provide specific directories that need to be updated via the `[path]` argument. This
 decreases the amount of AST the codemod needs to traverse and reduces the chances of the script
@@ -833,7 +822,7 @@ finished.
 yarn add @workday/canvas-kit-codemod --dev
 yarn canvas-kit-codemod v${canvasKitMajorVersionNumber} [path]
 yarn remove @workday/canvas-kit-codemod
-````
+```
 
 > **Note**: The codemod only works on `.js`, `.jsx`, `.ts`, and `.tsx` files. You'll need to
 > manually edit other file types (`.json`, `.mdx`, `.md`, etc.). You may need to run your linter