Workday · mannycarrera4 · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026
@@ -73,6 +73,11 @@ const EXTENDED_BRAND_TOKEN_MAP: Record<string, string> = {
   neutral150: '--cnvs-brand-neutral-150',
   neutral850: '--cnvs-brand-neutral-850',
   neutralA150: '--cnvs-brand-neutral-a150',
+  neutralA850: '--cnvs-brand-neutral-a850',
+  primaryA300: '--cnvs-brand-primary-a300',
+  criticalA300: '--cnvs-brand-critical-a300',
+  cautionA300: '--cnvs-brand-caution-a300',
+  positiveA300: '--cnvs-brand-positive-a300',
 };
 
 const setStyleVar = (style: React.CSSProperties, token: string, value: string) => {

@@ -15,93 +15,135 @@
  * | `sanaCanvasNumericalTheme` | Numerical `brand` shape for popup forwarding |
  * | `sanaCanvasProviderTheme` | Same — pass to root `CanvasProvider` when `<html>` is unavailable |
  */
+import {cssVar} from '@workday/canvas-kit-styling';
 import {base, brand} from '@workday/canvas-tokens-web';
 
 import type {CanvasNumericalBrandTheme} from './types';
 
-/** Reference a canvas-tokens CSS variable (resolves under `[data-theme="sana-canvas"]`). */
-const varRef = (token: string) => `var(${token})`;
-
 /**
- * Sana extends the neutral ramp with steps not yet exported from canvas-tokens-web JS.
- * Defined in `@workday/canvas-tokens-web/css/sana/_variables.css`.
+ * `base.sana` is a pre-built map of `var(--token, fallback)` strings exported by
+ * canvas-tokens-web specifically for these Sana-only base-palette steps — use them directly,
+ * not `cssVar()` (which expects a bare variable name, not an already-wrapped `var()` string).
+ * Referencing `base.*` (not `brand.*` of the same name) avoids a `var()` self-reference cycle:
+ * CanvasProvider writes each ramp entry onto the identically-named `--cnvs-brand-*` variable, so
+ * `brand.sana.neutral150` (itself `var(--cnvs-brand-neutral-150, ...)`) would point right back at
+ * the variable being written.
  */
-const sanaBrandNeutral = {
-  '150': '--cnvs-brand-neutral-150',
-  '850': '--cnvs-brand-neutral-850',
-  A150: '--cnvs-brand-neutral-a150',
-} as const;
+const sanaBaseNeutral = base.sana;
 
 /**
  * Sana Canvas brand tokens for scoped `CanvasProvider` / popup forwarding.
  * Values are `var()` references to Sana brand variables — not merged from `defaultCanvasTheme`.
+ *
+ * `action` and `neutral` are fully populated: Sana's palette is neutral/monochrome-driven, so
+ * `action.*` reads directly from the `neutral` ramp (see
+ * `@workday/canvas-tokens-web/css/sana/_variables.css`). `primary`/`critical`/`caution`/`positive`
+ * only set `A300` — the one step Sana actually redefines for those families (a stronger alpha
+ * wash on the matching hue) — every other key is intentionally omitted: Sana does not define a
+ * distinct value for it, so writing it here would only reference the very variable being written
+ * (a `var()` cycle that resolves to invalid, leaking the classic-theme fallback color instead of
+ * Sana's).
+ *
+ * `selected.fg`/`selected.surface` are forwarded too — they write directly onto
+ * `--cnvs-sys-color-brand-fg-selected`/`-surface-selected` (independent of the `primary` ramp),
+ * and Sana keeps selected `Menu.Item`/`Menu.Option` state on its neutral ramp
+ * (`neutralA900`/`neutralA100`), same as classic. Forwarding them keeps portaled popups in sync
+ * with in-document Sana styling and matches classic's own behavior — no color change intended.
+ *
+ * `system.color.brand.accent.primary`/`.action` and `.fg.primary.default`/`.strong` **are**
+ * forwarded (via the `system.color.brand.*` escape hatch — see
+ * {@link CanvasNumericalBrandTheme.system}) — unlike `selected`, Sana's stylesheet does
+ * redefine these four, to `brand.neutral.975` / `.A900` / `.A950`, so portaled popups need the
+ * override too for parity with in-document Sana styling.
+ *
+ * Ramp values must reference `base.*` (the underlying palette), never `brand.*` of the same
+ * name — CanvasProvider writes each entry onto the identically-named `--cnvs-brand-*` CSS
+ * variable, so referencing `brand.*` here would create that same self-reference cycle. The
+ * `system.color.brand.*` overrides above are the exception: they target *different* CSS
+ * variables (`--cnvs-sys-color-brand-*`) than the `brand.*` values they reference, so no cycle.
  */
 export const sanaCanvasNumericalTheme: CanvasNumericalBrandTheme = {
   // Explicit brand vars only — multi-key ramps write 1:1; no system shortcut bundles run.
   themeScope: 'brand',
   brand: {
-    action: {
-      base: varRef(brand.neutral975),
-      dark: varRef(brand.neutral950),
-      darkest: varRef(brand.neutral900),
-      accent: varRef(base.neutral0),
-      lightest: varRef(brand.neutral25),
-      lighter: varRef(brand.neutral50),
-      light: varRef(brand.neutral200),
-    },
-    neutral: {
-      '25': varRef(brand.neutral25),
-      '50': varRef(brand.neutral50),
-      '100': varRef(brand.neutral100),
-      '150': varRef(sanaBrandNeutral['150']),
-      '200': varRef(brand.neutral200),
-      '300': varRef(brand.neutral300),
-      '400': varRef(brand.neutral400),
-      '500': varRef(brand.neutral500),
-      '600': varRef(brand.neutral600),
-      '700': varRef(brand.neutral700),
-      '800': varRef(brand.neutral800),
-      '850': varRef(sanaBrandNeutral['850']),
-      '900': varRef(brand.neutral900),
-      '950': varRef(brand.neutral950),
-      '975': varRef(brand.neutral975),
-      A25: varRef(brand.neutralA25),
-      A50: varRef(brand.neutralA50),
-      A100: varRef(brand.neutralA100),
-      A150: varRef(sanaBrandNeutral.A150),
-      A200: varRef(brand.neutralA200),
-    },
     primary: {
-      '500': varRef(brand.primary500),
-      '600': varRef(brand.primary600),
-      '700': varRef(brand.primary700),
-      A25: varRef(brand.primaryA25),
-      A50: varRef(brand.primaryA50),
-      A100: varRef(brand.primaryA100),
+      A300: sanaBaseNeutral.blueA300,
     },
     critical: {
-      '500': varRef(brand.critical500),
-      '600': varRef(brand.critical600),
-      '700': varRef(brand.critical700),
-      A25: varRef(brand.criticalA25),
-      A50: varRef(brand.criticalA50),
+      A300: sanaBaseNeutral.redA300,
     },
     caution: {
-      '400': varRef(brand.caution400),
-      '500': varRef(brand.caution500),
-      A25: varRef(brand.cautionA25),
-      A50: varRef(brand.cautionA50),
+      A300: sanaBaseNeutral.amberA300,
     },
     positive: {
-      '600': varRef(brand.positive600),
-      '800': varRef(brand.positive800),
-      A25: varRef(brand.positiveA25),
-      A50: varRef(brand.positiveA50),
+      A300: sanaBaseNeutral.greenA300,
+    },
+    action: {
+      base: cssVar(brand.neutral975),
+      dark: cssVar(brand.neutral950),
+      darkest: cssVar(brand.neutral900),
+      darker: cssVar(brand.neutral975),
+      accent: cssVar(base.neutral0),
+      lightest: cssVar(brand.neutral25),
+      lighter: cssVar(brand.neutral50),
+      light: cssVar(brand.neutral200),
+    },
+    neutral: {
+      '25': cssVar(base.neutral25),
+      '50': cssVar(base.neutral50),
+      '100': cssVar(base.neutral100),
+      '150': sanaBaseNeutral.neutral150,
+      '200': cssVar(base.neutral200),
+      '300': cssVar(base.neutral300),
+      '400': cssVar(base.neutral400),
+      '500': cssVar(base.neutral500),
+      '600': cssVar(base.neutral600),
+      '700': cssVar(base.neutral700),
+      '800': cssVar(base.neutral800),
+      '850': sanaBaseNeutral.neutral850,
+      '900': cssVar(base.neutral900),
+      '950': cssVar(base.neutral950),
+      '975': cssVar(base.neutral975),
+      A25: cssVar(base.neutralA25),
+      A50: cssVar(base.neutralA50),
+      A100: cssVar(base.neutralA100),
+      A150: sanaBaseNeutral.neutralA150,
+      A200: cssVar(base.neutralA200),
+      A300: cssVar(base.neutralA300),
+      A400: cssVar(base.neutralA400),
+      A500: cssVar(base.neutralA500),
+      A600: cssVar(base.neutralA600),
+      A700: cssVar(base.neutralA700),
+      A800: cssVar(base.neutralA800),
+      A850: sanaBaseNeutral.neutralA850,
+      A900: cssVar(base.neutralA900),
+      A950: cssVar(base.neutralA950),
+      A975: cssVar(base.neutralA975),
     },
   },
+  // Selected Menu.Item/Menu.Option state — writes directly onto
+  // `--cnvs-sys-color-brand-fg-selected` / `-surface-selected` (not derived from
+  // `primary.700`/`primary.A50`, so no var() cycle risk referencing `brand.*` here).
+  // Sana keeps this on its neutral ramp rather than primary; forwarded for portal parity.
   selected: {
-    fg: varRef(brand.neutralA900),
-    surface: varRef(brand.neutralA100),
+    fg: cssVar(brand.neutralA900),
+    surface: cssVar(brand.neutralA100),
+  },
+  system: {
+    color: {
+      brand: {
+        accent: {
+          primary: cssVar(brand.neutral975),
+          action: cssVar(brand.neutral975),
+        },
+        fg: {
+          primary: {
+            default: cssVar(brand.neutralA900),
+            strong: cssVar(brand.neutralA950),
+          },
+        },
+      },
+    },
   },
 };
 
@@ -119,6 +161,15 @@ export const sanaCanvasNumericalTheme: CanvasNumericalBrandTheme = {
  * - Prefer setting `data-theme="sana-canvas"` on `<html>` with Sana CSS imported. Popups then
  *   inherit brand variables from the document and no `theme` prop is needed.
  *
+ * Selected `Menu.Item`/`Menu.Option` state (`--cnvs-sys-color-brand-fg-selected` /
+ * `-surface-selected`) is forwarded to Sana's neutral values (`neutralA900`/`neutralA100`,
+ * same as classic) so portaled popups match in-document Sana styling — no color change either way.
+ *
+ * `--cnvs-sys-color-brand-accent-primary`/`-accent-action`/`-fg-primary-default`/
+ * `-fg-primary-strong` are different: Sana's stylesheet *does* redefine them (to Sana neutral
+ * tones), so without this preset a popup outside `data-theme="sana-canvas"`'s reach falls back
+ * to classic primary-derived colors for those four, out of step with the rest of a Sana UI.
+ *
  * @example
  * ```tsx
  * // Preferred — control <html>

@@ -312,17 +312,34 @@ export type CanvasBrandRamp = Partial<
     | 'A25'
     | 'A50'
     | 'A100'
-    | 'A200',
+    | 'A200'
+    | 'A300',
     string
   >
 >;
 
 /**
- * Neutral brand ramp — includes Sana-only steps (`150` / `850` / `A150`) that are not
- * exported for primary/critical/caution/positive families.
+ * Neutral brand ramp — includes Sana-only steps (`150` / `850` / `A150` / `A850`), plus the
+ * extended alpha steps (`A400`–`A975`) that only the neutral family exposes.
  */
 export type CanvasNeutralBrandRamp = CanvasBrandRamp &
-  Partial<Record<'150' | '850' | 'A150', string>>;
+  Partial<
+    Record<
+      | '150'
+      | '850'
+      | 'A150'
+      | 'A400'
+      | 'A500'
+      | 'A600'
+      | 'A700'
+      | 'A800'
+      | 'A850'
+      | 'A900'
+      | 'A950'
+      | 'A975',
+      string
+    >
+  >;
 
 /** Semantic keys for `brand.action.*` CSS variables (PrimaryButton, etc.). */
 export type CanvasActionBrandRamp = Partial<

@@ -5,6 +5,16 @@ import {CanvasProvider} from '../lib/CanvasProvider';
 import {sanaCanvasProviderTheme} from '../lib/theming/sanaTheme';
 
 describe('CanvasProvider', () => {
+  it('forwards data-theme onto the wrapper div', () => {
+    const {container} = render(
+      <CanvasProvider theme={sanaCanvasProviderTheme} data-theme="sana-canvas">
+        <div>Test</div>
+      </CanvasProvider>
+    );
+
+    expect(container.firstElementChild?.getAttribute('data-theme')).toBe('sana-canvas');
+  });
+
   describe('console warnings', () => {
     it('should warn when sanaCanvasProviderTheme is used with global Sana theme', () => {
       const consoleSpy = vi.spyOn(global.console, 'warn').mockImplementation(() => {});

@@ -5,26 +5,83 @@ import {defaultCanvasTheme} from '../lib/theming';
 import {sanaCanvasNumericalTheme, sanaCanvasProviderTheme} from '../lib/theming/sanaTheme';
 
 describe('sanaCanvasNumericalTheme', () => {
-  it('references Sana brand CSS variables instead of defaultCanvasTheme literals', () => {
-    expect(sanaCanvasNumericalTheme.brand?.neutral?.['600']).toBe(`var(${brand.neutral600})`);
+  it('references Sana base-palette CSS variables instead of defaultCanvasTheme literals', () => {
+    expect(sanaCanvasNumericalTheme.brand?.neutral?.['600']).toBe(`var(${base.neutral600})`);
     expect(sanaCanvasNumericalTheme.brand?.action?.base).toBe(`var(${brand.neutral975})`);
     expect(sanaCanvasNumericalTheme.brand?.action?.accent).toBe(`var(${base.neutral0})`);
     expect(sanaCanvasNumericalTheme.brand?.neutral?.['600']).not.toBe(
       defaultCanvasTheme.palette.neutral.main
     );
   });
 
+  it('never references the same CSS variable name it writes to (would create a var() cycle)', () => {
+    const {style} = canvasThemeToCssVars(sanaCanvasProviderTheme, {});
+    Object.entries(style).forEach(([key, value]) => {
+      if (key.startsWith('--') && typeof value === 'string') {
+        expect(value).not.toBe(`var(${key})`);
+      }
+    });
+  });
+
+  it("only writes the A300 step of primary/critical/caution/positive (Sana's one distinct value)", () => {
+    expect(Object.keys(sanaCanvasNumericalTheme.brand?.primary ?? {})).toEqual(['A300']);
+    expect(Object.keys(sanaCanvasNumericalTheme.brand?.critical ?? {})).toEqual(['A300']);
+    expect(Object.keys(sanaCanvasNumericalTheme.brand?.caution ?? {})).toEqual(['A300']);
+    expect(Object.keys(sanaCanvasNumericalTheme.brand?.positive ?? {})).toEqual(['A300']);
+
+    const {style} = canvasThemeToCssVars(sanaCanvasProviderTheme, {});
+    expect(style['--cnvs-brand-primary-a300' as any]).toBe(base.sana.blueA300);
+    expect(style['--cnvs-brand-critical-a300' as any]).toBe(base.sana.redA300);
+    expect(style['--cnvs-brand-caution-a300' as any]).toBe(base.sana.amberA300);
+    expect(style['--cnvs-brand-positive-a300' as any]).toBe(base.sana.greenA300);
+  });
+
   it('writes brand tokens when passed to canvasThemeToCssVars', () => {
     const {style} = canvasThemeToCssVars(sanaCanvasProviderTheme, {});
     expect(Object.keys(style).length).toBeGreaterThan(0);
-    expect(style[brand.neutral600 as any]).toBe(`var(${brand.neutral600})`);
+    expect(style[brand.neutral600 as any]).toBe(`var(${base.neutral600})`);
     expect(style[brand.action.base as any]).toBe(`var(${brand.neutral975})`);
   });
 
-  it('writes Sana extended neutral ramp keys', () => {
+  it('writes Sana extended neutral ramp keys from the base palette', () => {
+    const {style} = canvasThemeToCssVars(sanaCanvasProviderTheme, {});
+    expect(style['--cnvs-brand-neutral-150' as any]).toBe(base.sana.neutral150);
+    expect(style['--cnvs-brand-neutral-850' as any]).toBe(base.sana.neutral850);
+    expect(style['--cnvs-brand-neutral-a150' as any]).toBe(base.sana.neutralA150);
+    expect(style['--cnvs-brand-neutral-a850' as any]).toBe(base.sana.neutralA850);
+  });
+
+  it('writes the full neutral alpha ramp through A975 (not just up to A200)', () => {
+    const {style} = canvasThemeToCssVars(sanaCanvasProviderTheme, {});
+    expect(style[brand.neutralA300 as any]).toBe(`var(${base.neutralA300})`);
+    expect(style[brand.neutralA900 as any]).toBe(`var(${base.neutralA900})`);
+    expect(style[brand.neutralA975 as any]).toBe(`var(${base.neutralA975})`);
+  });
+
+  it('writes action.darker alongside the rest of the action bundle', () => {
+    const {style} = canvasThemeToCssVars(sanaCanvasProviderTheme, {});
+    expect(style[brand.action.darker as any]).toBe(`var(${brand.neutral975})`);
+  });
+
+  it('forwards selected.fg/selected.surface using Sana neutral values (no color change from classic)', () => {
     const {style} = canvasThemeToCssVars(sanaCanvasProviderTheme, {});
-    expect(style['--cnvs-brand-neutral-150' as any]).toBe('var(--cnvs-brand-neutral-150)');
-    expect(style['--cnvs-brand-neutral-850' as any]).toBe('var(--cnvs-brand-neutral-850)');
-    expect(style['--cnvs-brand-neutral-a150' as any]).toBe('var(--cnvs-brand-neutral-a150)');
+    expect(style['--cnvs-sys-color-brand-fg-selected' as any]).toBe(`var(${brand.neutralA900})`);
+    expect(style['--cnvs-sys-color-brand-surface-selected' as any]).toBe(
+      `var(${brand.neutralA100})`
+    );
+  });
+
+  it('forwards accent.primary/action and fg.primary.default/strong for portal parity', () => {
+    // Unlike `selected`, Sana's stylesheet redefines these four `system.color.brand.*`
+    // tokens, so popups outside `[data-theme="sana-canvas"]`'s reach need the override too.
+    const {style} = canvasThemeToCssVars(sanaCanvasProviderTheme, {});
+    expect(style['--cnvs-sys-color-brand-accent-primary' as any]).toBe(`var(${brand.neutral975})`);
+    expect(style['--cnvs-sys-color-brand-accent-action' as any]).toBe(`var(${brand.neutral975})`);
+    expect(style['--cnvs-sys-color-brand-fg-primary-default' as any]).toBe(
+      `var(${brand.neutralA900})`
+    );
+    expect(style['--cnvs-sys-color-brand-fg-primary-strong' as any]).toBe(
+      `var(${brand.neutralA950})`
+    );
   });
 });
@@ -118,6 +118,11 @@ import {CanvasProvider} from '@workday/canvas-kit-react/common';
 </CanvasProvider>
 ```
 
+Selected `Menu.Item`/`Menu.Option` state (`--cnvs-sys-color-brand-fg-selected` /
+`-surface-selected`) uses Sana's neutral ramp (`neutralA900`/`neutralA100`), the same values as
+classic Canvas — selection styling doesn't change under Sana, whether or not
+`data-theme="sana-canvas"` is set.
+
 **Scoped / no document-root control:** if you cannot set `data-theme` on `<html>` (embedded apps,
 microfrontends, third-party shells), a nested `data-theme` alone does **not** reach portaled
 popups. Pass both `data-theme="sana-canvas"` (for in-tree UI) and `sanaCanvasProviderTheme` (so