@workday/canvas-kit-react 16.0.0-alpha.0499-next.0 → 16.0.0

package/common/lib/CanvasProvider.tsx

@@ -1,117 +1,59 @@
 import {CacheProvider, Theme, ThemeProvider} from '@emotion/react';
 import * as React from 'react';
 
-import {createStyles, getCache, maybeWrapCSSVariables} from '@workday/canvas-kit-styling';
+import {createStyles, getCache} from '@workday/canvas-kit-styling';
 import {base, brand, system} from '@workday/canvas-tokens-web';
 
-import {PartialEmotionCanvasTheme, defaultCanvasTheme, useTheme} from './theming';
+import {
+  CanvasProviderTheme,
+  CanvasThemingScope,
+  EmotionCanvasTheme,
+  PartialEmotionCanvasTheme,
+  defaultCanvasTheme,
+  getTheme,
+  isNumericalTheme,
+  resolveThemingScope,
+  useTheme,
+} from './theming';
+import {
+  hasExplicitSemanticPalette,
+  writeBrandScopeSemantic,
+  writeNumericalTheme,
+  writeSemanticTheme,
+} from './theming/brandScope';
+import {sanaCanvasProviderTheme} from './theming/sanaTheme';
+
+/**
+ * Context for providing brand CSS variables to popup containers.
+ * This carries the resolved CSS variable style map from CanvasProvider
+ * to usePopupStack for proper popup theming, regardless of whether
+ * a numerical or legacy theme is used.
+ */
+export const CanvasBrandStyleContext = React.createContext<React.CSSProperties>({});
 
 export interface CanvasProviderProps {
   /**
    * ⚠️ Only use this prop if you intent to to theme a part of your application that is different from global theming.
-   * For more information, view our [Theming Docs](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs#global-vs-scoped-theming).
+   * For more information, view our [Theming Docs](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs#scoped-theming).
    *
    * While we support theme overrides, we advise to use global theming via CSS Variables.
    */
-  theme?: PartialEmotionCanvasTheme;
+  theme?: CanvasProviderTheme;
+  /**
+   * How partial theme input expands. Default `'brand'`.
+   *
+   * **Numerical `brand` shape:** `'brand'` applies the `primary['600']` shortcut
+   * (PrimaryButton + selected states). `'full'` writes each ramp key literally with
+   * no shortcuts. Other `brand.*` keys always map 1:1 to CSS variables.
+   *
+   * **Legacy `canvas.palette` shape:** `'brand'` = primary.main shortcut only.
+   * `'full'` = auto-generated ramps + broad `system.color.brand.*` forwarding.
+   *
+   * @default 'brand'
+   */
+  themeScope?: CanvasThemingScope;
 }
 
-const mappedKeys = {
-  lightest: 'lightest',
-  lighter: 'lighter',
-  light: 'light',
-  main: 'base',
-  dark: 'dark',
-  darkest: 'darkest',
-  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`
- * `alert` -> `caution`
- * `neutral` -> `neutral`
- */
-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.
- *
- * ## 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 `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 `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`
- *
- * ### 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
-  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.
  */
@@ -158,12 +100,6 @@ export const defaultBranding = createStyles({
   [brand.gradient.primary]:
     `linear-gradient(90deg, ${brand.primary.base} 0%, ${brand.primary.dark} 100%)`,
 
-  /**
-   * Default `system.color.brand.*` values on the provider scope so components that read
-   * system tokens first (e.g. `cssVar(system.color.brand.accent.primary, brand.primary.base)`)
-   * still resolve to the same branding as legacy `brand.*` vars when globals define system
-   * tokens differently, or when consumers override `brand.*` via `className`.
-   */
   [system.color.brand.focus.primary]: brand.common.focusOutline,
   [system.color.brand.border.primary]: brand.common.focusOutline,
   [system.color.brand.accent.primary]: brand.primary.base,
@@ -202,240 +138,136 @@ export const defaultBranding = createStyles({
   [system.color.brand.surface.selected]: brand.primary.lighter,
 });
 
+/** Pure function — safe to call outside React hooks (e.g. usePopupStack). */
+export function canvasThemeToCssVars(
+  theme: CanvasProviderTheme | undefined,
+  elemProps: React.HTMLAttributes<HTMLElement>,
+  options?: {
+    themeScope?: CanvasThemingScope;
+    filledSemanticTheme?: EmotionCanvasTheme;
+  }
+) {
+  const className = elemProps.className || '';
+  const style: React.CSSProperties = {...(elemProps.style || {})};
+  const scope = options?.themeScope ?? resolveThemingScope(theme);
+
+  if (!theme) {
+    return {...elemProps, className, style};
+  }
+
+  if (isNumericalTheme(theme)) {
+    writeNumericalTheme(theme, style, scope);
+  } else if (!hasExplicitSemanticPalette(theme)) {
+    // `{canvas: {}}` — no inline overrides; global CSS (e.g. Sana) cascades through.
+  } else if (scope === 'brand') {
+    writeBrandScopeSemantic(theme, style);
+  } else {
+    const filledTheme =
+      options?.filledSemanticTheme ?? getTheme(theme as PartialEmotionCanvasTheme);
+    writeSemanticTheme(filledTheme.canvas.palette, style, {writeAll: true});
+  }
+
+  return {...elemProps, className, style};
+}
+
 export const useCanvasThemeToCssVars = (
   /**
    * @deprecated ⚠️ `theme` is deprecated. In previous versions of Canvas Kit, we allowed teams to pass a theme object, this supported [Emotion's theming](https://emotion.sh/docs/theming). Now that we're shifting to a global theming approach based on CSS variables, we advise to no longer using the theme prop. For more information, view our [Theming Docs](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs#-preferred-approach-v14).
    */
-  theme: PartialEmotionCanvasTheme | undefined,
-  elemProps: React.HTMLAttributes<HTMLElement>
+  theme: CanvasProviderTheme | undefined,
+  elemProps: React.HTMLAttributes<HTMLElement>,
+  themeScope?: CanvasThemingScope
 ) => {
-  const filledTheme = useTheme(theme);
-  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[key]] = value;
-
-          // Forward to new brand.common tokens
-          //@ts-ignore
-          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;
-          }
-
-          // 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;
-          }
-
-          // Additional system token forwarding for errorInner
-          if (key === 'errorInner') {
-            // Forward errorInner to system.color.brand.focus.critical and system.color.brand.border.critical
-            // These tokens are used by components (e.g., TextInput with error="error", Switch) for critical
-            // focus ring and border styling. Maps to brand.critical500 via brand.common.errorInner.
-            // This ensures backwards compatibility when users customize errorInner in their theme.
-            // @ts-ignore
-            style[system.color.brand.focus.critical] = value;
-            // @ts-ignore
-            style[system.color.brand.border.critical] = value;
-          }
-        }
-      });
-    } 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 when 'main' changes — unless focusOutline was customized (it takes precedence)
-                if (newBrandColor === 'primary') {
-                  const focusOutlineCustomized =
-                    palette.common.focusOutline !== defaultCanvasTheme.palette.common.focusOutline;
-                  if (!focusOutlineCustomized) {
-                    // @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;
-                  }
-                }
-
-                // system.color.brand.focus.critical & system.color.brand.border.critical -> brand.critical.500 (palette.error.dark)
-                if (newBrandColor === 'critical') {
-                  // @ts-ignore
-                  const focusCriticalToken = system.color.brand.focus.critical;
-                  if (focusCriticalToken) {
-                    // @ts-ignore
-                    style[focusCriticalToken] = value;
-                  }
-                  // @ts-ignore
-                  const borderCriticalToken = system.color.brand.border.critical;
-                  if (borderCriticalToken) {
-                    // @ts-ignore
-                    style[borderCriticalToken] = value;
-                  }
-                }
-
-                // system.color.brand.focus.caution.outer & system.color.brand.border.caution -> brand.caution.500 (palette.alert.dark)
-                if (newBrandColor === 'caution') {
-                  // @ts-ignore
-                  const focusCautionOuterToken = system.color.brand.focus.caution?.outer;
-                  if (focusCautionOuterToken) {
-                    // @ts-ignore
-                    style[focusCautionOuterToken] = value;
-                  }
-                  // @ts-ignore
-                  const borderCautionToken = system.color.brand.border.caution;
-                  if (borderCautionToken) {
-                    // @ts-ignore
-                    style[borderCautionToken] = 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;
-                }
+  const filledTheme = useTheme(
+    isNumericalTheme(theme) ? undefined : (theme as PartialEmotionCanvasTheme)
+  );
+  const resolvedScope = themeScope ?? resolveThemingScope(theme);
 
-                // 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 canvasThemeToCssVars(theme, elemProps, {
+    themeScope: resolvedScope,
+    filledSemanticTheme:
+      !isNumericalTheme(theme) && resolvedScope === 'full' ? filledTheme : undefined,
   });
-
-  return {...elemProps, className, style};
 };
 
 export const CanvasProvider = ({
   children,
-  theme = {canvas: {}}, // default to empty theme to avoid breaking changes
+  theme,
+  themeScope,
   ...props
 }: CanvasProviderProps & React.HTMLAttributes<HTMLElement>) => {
-  const {className, ...elemProps} = useCanvasThemeToCssVars(theme, props);
+  // Add console warning for unnecessary sanaCanvasProviderTheme usage
+  React.useEffect(() => {
+    if (process.env.NODE_ENV !== 'production') {
+      if (
+        theme === sanaCanvasProviderTheme &&
+        typeof document !== 'undefined' &&
+        document.documentElement.getAttribute('data-theme') === 'sana-canvas'
+      ) {
+        console.warn(
+          'Canvas Kit: You are passing sanaCanvasProviderTheme to CanvasProvider but ' +
+            'data-theme="sana-canvas" is already set on <html>. The theme prop is not needed ' +
+            'in this case and can be removed. Keep sanaCanvasProviderTheme when you cannot ' +
+            'control <html> (embedded apps / microfrontends) so popups still get Sana brand ' +
+            'variables. See: ' +
+            'https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs'
+        );
+      }
+    }
+  }, [theme]);
+
+  // Computed className/style win over consumer props — do not re-spread `props` over them.
+  const {className, style, ...elemProps} = useCanvasThemeToCssVars(theme, props, themeScope);
   const cache = getCache();
-  const rest = {...elemProps, ...props};
+
+  // Read parent context to support nested scoped providers
+  const parentBrandStyle = React.useContext(CanvasBrandStyleContext);
+
+  // Popup forwarding only needs CSS custom properties (not consumer layout styles).
+  const mergedBrandStyle = React.useMemo(() => {
+    const merged: React.CSSProperties = {};
+    for (const [key, value] of Object.entries({...parentBrandStyle, ...style})) {
+      if (key.startsWith('--') && typeof value === 'string') {
+        // @ts-ignore - CSS custom property key
+        merged[key] = value;
+      }
+    }
+    return merged;
+  }, [parentBrandStyle, style]);
+
+  const emotionTheme = theme
+    ? isNumericalTheme(theme)
+      ? ({canvas: defaultCanvasTheme} as Theme)
+      : (theme as Theme)
+    : undefined;
+  const content = (
+    <div
+      dir={
+        isNumericalTheme(theme)
+          ? theme.direction || defaultCanvasTheme.direction
+          : theme?.canvas?.direction || defaultCanvasTheme.direction
+      }
+      className={className}
+      {...(elemProps as React.HTMLAttributes<HTMLDivElement>)}
+      style={style}
+    >
+      {children}
+    </div>
+  );
+
+  const wrappedContent = (
+    <CanvasBrandStyleContext.Provider value={mergedBrandStyle}>
+      {content}
+    </CanvasBrandStyleContext.Provider>
+  );
+
   return (
     <CacheProvider value={cache}>
-      <ThemeProvider theme={theme as Theme}>
-        <div
-          dir={theme?.canvas?.direction || defaultCanvasTheme.direction}
-          {...(rest as React.HTMLAttributes<HTMLDivElement>)}
-        >
-          {children}
-        </div>
-      </ThemeProvider>
+      {emotionTheme ? (
+        <ThemeProvider theme={emotionTheme}>{wrappedContent}</ThemeProvider>
+      ) : (
+        wrappedContent
+      )}
     </CacheProvider>
   );
 };

package/common/lib/theming/README.md

@@ -6,6 +6,13 @@
 > guide, see our
 > [Theming Documentation](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs).
 
+## Sana Canvas Theme
+
+For application-level theming in v16, import the Sana CSS variables and set `data-theme="sana-canvas"`
+on `<html>`. See the
+[v16 Upgrade Guide](https://workday.github.io/canvas-kit/?path=/docs/guides-upgrade-guides-v-16-0-overview--docs#sana-canvas-theme)
+for the canonical setup. The `CanvasProvider` `theme` prop is for **scoped** theming only.
+
 ## Installation
 
 ```sh
@@ -14,7 +21,7 @@ yarn add @workday/canvas-kit-react/common
 
 ## Recommended Approach: CSS Variables
 
-Canvas Kit v14+ promotes using CSS variables for theming. Import CSS variable files and override
+Canvas Kit v16 promotes using CSS variables for theming. Import CSS variable files and override
 values in your root CSS:
 
 ```css
@@ -23,12 +30,13 @@ values in your root CSS:
 @import '@workday/canvas-tokens-web/css/system/_variables.css';
 @import '@workday/canvas-tokens-web/css/brand/_variables.css';
 @import '@workday/canvas-tokens-web/css/component/_variables.css';
+@import '@workday/canvas-tokens-web/css/sana/_variables.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-dark: var(--cnvs-base-palette-magenta-700);
+  --cnvs-brand-primary-600: var(--cnvs-base-palette-magenta-600);
+  --cnvs-brand-primary-500: var(--cnvs-base-palette-magenta-500);
+  --cnvs-brand-primary-A50: var(--cnvs-base-palette-magenta-A50);
 }
 ```
 
@@ -40,8 +48,8 @@ import {createStyles} from '@workday/canvas-kit-styling';
 import {base, brand} from '@workday/canvas-tokens-web';
 
 const themedBrand = createStyles({
-  [brand.primary.base]: base.legacy.magenta600,
-  [brand.primary.dark]: base.legacy.magenta700,
+  [brand.primary600]: base.magenta600,
+  [brand.primary700]: base.magenta700,
 });
 
 <CanvasProvider className={themedBrand}>
@@ -49,6 +57,41 @@ const themedBrand = createStyles({
 </CanvasProvider>;
 ```
 
+## Scoped Theming (CanvasProvider)
+
+For embedded or multi-brand sections, use the numerical `brand` shape:
+
+```tsx
+import {CanvasProvider} from '@workday/canvas-kit-react/common';
+import {base} from '@workday/canvas-tokens-web';
+
+<CanvasProvider theme={{brand: {primary: {'600': base.magenta600}}}}>
+  <ScopedSection />
+</CanvasProvider>
+```
+
+### Popups and `sanaCanvasProviderTheme`
+
+Popups (menus, selects, modals) portal to `document.body`. Theme inheritance depends on where
+`data-theme="sana-canvas"` lives:
+
+- **You control `<html>`:** set `data-theme="sana-canvas"` there. Popups inherit Sana variables —
+  no `theme` prop needed.
+- **You cannot control `<html>`** (embedded apps, microfrontends, third-party shells): pass
+  `sanaCanvasProviderTheme` to your root `CanvasProvider`. Nested `data-theme` on a wrapper does
+  not reach portaled popups; this preset forwards Sana brand variables onto the popup stack.
+
+```tsx
+import {CanvasProvider, sanaCanvasProviderTheme} from '@workday/canvas-kit-react/common';
+
+// Required when <html> is unavailable
+<CanvasProvider theme={sanaCanvasProviderTheme}>
+  <App />
+</CanvasProvider>
+```
+
+See the [Theming documentation](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs) for details.
+
 ## Bidirectionality (RTL Support)
 
 ### Setting RTL Direction