From 6790fc08046dbb8d0d9473eaa5df53337665afb9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 26 Oct 2026 10:29:01 +0000
Subject: [PATCH 01/20] [system][material-ui] Scope the CSS theme variables of
 nested and sibling ThemeProviders

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HG4YYGmgsLG7riohZnG1WZ
---
 packages/mui-material/src/Modal/Modal.js      |   6 +
 packages/mui-material/src/Popper/Popper.tsx   |   6 +
 .../mui-material/src/styles/ThemeProvider.tsx |  18 ++
 .../src/styles/ThemeProviderScoped.test.tsx   | 224 ++++++++++++++++++
 .../src/styles/createThemeFoundation.ts       |   9 +
 .../src/styles/createThemeWithVars.js         |   4 +-
 packages/mui-material/src/styles/index.d.ts   |   3 +-
 packages/mui-material/src/styles/index.js     |   1 +
 .../src/cssVars/ThemeScopeContext.ts          |  33 +++
 .../src/cssVars/createCssVarsProvider.tsx     | 202 ++++++++++++++--
 .../src/cssVars/createCssVarsTheme.ts         |   1 +
 packages/mui-system/src/cssVars/index.ts      |   2 +
 .../mui-system/src/cssVars/prepareCssVars.ts  |  68 +++---
 .../src/cssVars/scopeCssVars.test.ts          | 117 +++++++++
 .../mui-system/src/cssVars/scopeCssVars.ts    | 163 +++++++++++++
 15 files changed, 800 insertions(+), 57 deletions(-)
 create mode 100644 packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
 create mode 100644 packages/mui-system/src/cssVars/ThemeScopeContext.ts
 create mode 100644 packages/mui-system/src/cssVars/scopeCssVars.test.ts
 create mode 100644 packages/mui-system/src/cssVars/scopeCssVars.ts

diff --git a/packages/mui-material/src/Modal/Modal.js b/packages/mui-material/src/Modal/Modal.js
index 2abe753d453182..febed1c4ddf008 100644
--- a/packages/mui-material/src/Modal/Modal.js
+++ b/packages/mui-material/src/Modal/Modal.js
@@ -5,6 +5,7 @@ import clsx from 'clsx';
 import HTMLElementType from '@mui/utils/HTMLElementType';
 import elementAcceptingRef from '@mui/utils/elementAcceptingRef';
 import composeClasses from '@mui/utils/composeClasses';
+import { useThemeScope } from '@mui/system/cssVars';
 import FocusTrap from '../Unstable_TrapFocus';
 import Portal from '../Portal';
 import { styled } from '../zero-styled';
@@ -147,17 +148,22 @@ const Modal = React.forwardRef(function Modal(inProps, ref) {
 
   const externalForwardedProps = { slots, slotProps };
 
+  // The modal is portaled out of a scoped ThemeProvider's element, so it applies the scope itself.
+  const { className: themeScopeClassName, ...themeScopeAttributes } = useThemeScope();
+
   const [RootSlot, rootProps] = useSlot('root', {
     ref,
     elementType: ModalRoot,
     externalForwardedProps: {
       ...externalForwardedProps,
+      ...themeScopeAttributes,
       ...other,
       component,
     },
     getSlotProps: getRootProps,
     ownerState,
     className: clsx(
+      themeScopeClassName,
       className,
       classes?.root,
       !ownerState.open && ownerState.exited && classes?.hidden,
diff --git a/packages/mui-material/src/Popper/Popper.tsx b/packages/mui-material/src/Popper/Popper.tsx
index 5552227c2920aa..e996d68ddab99d 100644
--- a/packages/mui-material/src/Popper/Popper.tsx
+++ b/packages/mui-material/src/Popper/Popper.tsx
@@ -1,6 +1,8 @@
 'use client';
 import { SxProps } from '@mui/system';
 import { useRtl } from '@mui/system/RtlProvider';
+import { useThemeScope } from '@mui/system/cssVars';
+import clsx from 'clsx';
 import refType from '@mui/utils/refType';
 import HTMLElementType from '@mui/utils/HTMLElementType';
 import PropTypes from 'prop-types';
@@ -45,6 +47,8 @@ const Popper = React.forwardRef(function Popper(
   ref: React.ForwardedRef<HTMLDivElement>,
 ) {
   const isRtl = useRtl();
+  // The popper is portaled out of a scoped ThemeProvider's element, so it applies the scope itself.
+  const { className: themeScopeClassName, ...themeScopeAttributes } = useThemeScope();
   const props = useDefaultProps({
     props: inProps,
     name: 'MuiPopper',
@@ -86,7 +90,9 @@ const Popper = React.forwardRef(function Popper(
       direction={isRtl ? 'rtl' : 'ltr'}
       slots={slots}
       slotProps={slotProps}
+      {...themeScopeAttributes}
       {...otherProps}
+      className={clsx(themeScopeClassName, otherProps.className) || undefined}
       ref={ref}
     />
   );
diff --git a/packages/mui-material/src/styles/ThemeProvider.tsx b/packages/mui-material/src/styles/ThemeProvider.tsx
index b3f45c0f65f267..7c297702ed97d1 100644
--- a/packages/mui-material/src/styles/ThemeProvider.tsx
+++ b/packages/mui-material/src/styles/ThemeProvider.tsx
@@ -32,6 +32,24 @@ type ThemeProviderCssVariablesProps = CssThemeVariables extends { enabled: true
        * @default false
        */
       forceThemeRerender?: boolean | undefined;
+      /**
+       * If `true`, the CSS theme variables are set on an element that wraps the children instead of `:root`,
+       * so they don't affect the rest of the page. Use it for a provider that isn't nested in another one,
+       * like an embedded widget. Nested providers are scoped automatically when their variables differ.
+       *
+       * A string is used as a readable part of the class name, and to suffix the storage keys.
+       * @default false
+       */
+      scoped?: boolean | string | undefined;
+      /**
+       * The element that wraps the children of a scoped provider.
+       * By default, a `div` with `display: contents`.
+       */
+      component?: React.ElementType | undefined;
+      /**
+       * The class name of the element that wraps the children of a scoped provider.
+       */
+      className?: string | undefined;
     }
   : {};
 
diff --git a/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx b/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
new file mode 100644
index 00000000000000..3ea187353b48f7
--- /dev/null
+++ b/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
@@ -0,0 +1,224 @@
+import { describe, it, expect } from 'vitest';
+import * as React from 'react';
+import { createRenderer, screen, isJsdom } from '@mui/internal-test-utils';
+import Button from '@mui/material/Button';
+import Dialog from '@mui/material/Dialog';
+import Popper from '@mui/material/Popper';
+import { ThemeProvider, createTheme, useThemeScope } from '@mui/material/styles';
+
+function getVar(element: Element, name: string) {
+  return getComputedStyle(element).getPropertyValue(name).trim();
+}
+
+const blueTheme = createTheme({ cssVariables: true, palette: { primary: { main: '#0000ff' } } });
+const redTheme = createTheme({ cssVariables: true, palette: { primary: { main: '#ff0000' } } });
+
+describe('ThemeProvider with scoped CSS theme variables', () => {
+  const { render } = createRenderer();
+
+  describe('nested', () => {
+    it('wraps the children in a scoped element when the variables differ', () => {
+      render(
+        <ThemeProvider theme={blueTheme}>
+          <div data-testid="outer">
+            <ThemeProvider theme={redTheme}>
+              <div data-testid="inner" />
+            </ThemeProvider>
+          </div>
+        </ThemeProvider>,
+      );
+      const wrapper = screen.getByTestId('inner').parentElement!;
+      expect(wrapper).not.to.equal(screen.getByTestId('outer'));
+      expect(wrapper.className).to.match(/^mui-theme-[a-z0-9]+$/);
+      expect(wrapper.style.display).to.equal('contents');
+    });
+
+    it('renders no element when the theme is the same', () => {
+      render(
+        <ThemeProvider theme={blueTheme}>
+          <div data-testid="outer">
+            <ThemeProvider theme={blueTheme}>
+              <div data-testid="inner" />
+            </ThemeProvider>
+          </div>
+        </ThemeProvider>,
+      );
+      expect(screen.getByTestId('inner').parentElement).to.equal(screen.getByTestId('outer'));
+    });
+
+    it('renders no element when the theme only changes component defaults', () => {
+      const theme = createTheme({
+        cssVariables: true,
+        palette: { primary: { main: '#0000ff' } },
+        components: { MuiButton: { defaultProps: { disableRipple: true } } },
+      });
+      render(
+        <ThemeProvider theme={blueTheme}>
+          <div data-testid="outer">
+            <ThemeProvider theme={theme}>
+              <div data-testid="inner" />
+            </ThemeProvider>
+          </div>
+        </ThemeProvider>,
+      );
+      expect(screen.getByTestId('inner').parentElement).to.equal(screen.getByTestId('outer'));
+    });
+
+    it.skipIf(isJsdom())('applies the inner variables only to the children', () => {
+      render(
+        <ThemeProvider theme={blueTheme}>
+          <Button variant="contained" data-testid="outer">
+            Outer
+          </Button>
+          <ThemeProvider theme={redTheme}>
+            <Button variant="contained" data-testid="inner">
+              Inner
+            </Button>
+          </ThemeProvider>
+        </ThemeProvider>,
+      );
+      expect(getVar(screen.getByTestId('outer'), '--mui-palette-primary-main')).to.equal('#0000ff');
+      expect(getVar(screen.getByTestId('inner'), '--mui-palette-primary-main')).to.equal('#ff0000');
+      expect(getComputedStyle(screen.getByTestId('inner')).backgroundColor).to.equal(
+        'rgb(255, 0, 0)',
+      );
+    });
+
+    it.skipIf(isJsdom())('applies the inner variables to portaled dialogs and poppers', () => {
+      function Anchored() {
+        const [anchorEl, setAnchorEl] = React.useState<HTMLElement | null>(null);
+        return (
+          <React.Fragment>
+            <div ref={setAnchorEl} />
+            <Popper open={!!anchorEl} anchorEl={anchorEl} data-testid="popper">
+              popper
+            </Popper>
+          </React.Fragment>
+        );
+      }
+      render(
+        <ThemeProvider theme={blueTheme}>
+          <ThemeProvider theme={redTheme}>
+            <Dialog open>
+              <div data-testid="dialog-content" />
+            </Dialog>
+            <Anchored />
+          </ThemeProvider>
+        </ThemeProvider>,
+      );
+      expect(getVar(screen.getByTestId('dialog-content'), '--mui-palette-primary-main')).to.equal(
+        '#ff0000',
+      );
+      expect(getVar(screen.getByTestId('popper'), '--mui-palette-primary-main')).to.equal(
+        '#ff0000',
+      );
+    });
+
+    it.skipIf(isJsdom())('follows the outer color scheme', () => {
+      const outer = createTheme({
+        cssVariables: { colorSchemeSelector: 'class' },
+        colorSchemes: { light: true, dark: true },
+      });
+      const inner = createTheme({
+        cssVariables: { colorSchemeSelector: 'class' },
+        colorSchemes: {
+          light: { palette: { primary: { main: '#ff0000' } } },
+          dark: { palette: { primary: { main: '#00ff00' } } },
+        },
+      });
+      render(
+        <ThemeProvider theme={outer} defaultMode="dark" storageManager={null}>
+          <ThemeProvider theme={inner}>
+            <div data-testid="inner" />
+          </ThemeProvider>
+        </ThemeProvider>,
+      );
+      expect(document.documentElement.classList.contains('dark')).to.equal(true);
+      expect(getVar(screen.getByTestId('inner'), '--mui-palette-primary-main')).to.equal('#00ff00');
+      document.documentElement.classList.remove('dark');
+    });
+  });
+
+  describe('scoped prop', () => {
+    it.skipIf(isJsdom())('keeps a sibling provider off :root', () => {
+      const darkTheme = createTheme({
+        cssVariables: true,
+        palette: { mode: 'dark', primary: { main: '#ff0000' } },
+      });
+      render(
+        <React.Fragment>
+          <ThemeProvider theme={blueTheme}>
+            <div data-testid="app" />
+          </ThemeProvider>
+          <ThemeProvider theme={darkTheme} scoped>
+            <div data-testid="widget" />
+          </ThemeProvider>
+        </React.Fragment>,
+      );
+      expect(getVar(document.documentElement, '--mui-palette-primary-main')).to.equal('#0000ff');
+      expect(getComputedStyle(document.documentElement).colorScheme).not.to.equal('dark');
+      expect(getVar(screen.getByTestId('app'), '--mui-palette-primary-main')).to.equal('#0000ff');
+      expect(getVar(screen.getByTestId('widget'), '--mui-palette-primary-main')).to.equal(
+        '#ff0000',
+      );
+      expect(getComputedStyle(screen.getByTestId('widget')).colorScheme).to.equal('dark');
+    });
+
+    it('uses the name in the class name', () => {
+      render(
+        <ThemeProvider theme={redTheme} scoped="widget">
+          <div data-testid="widget" />
+        </ThemeProvider>,
+      );
+      expect(screen.getByTestId('widget').parentElement!.className).to.match(
+        /^mui-theme-widget-[a-z0-9]+$/,
+      );
+    });
+
+    it('warns when two providers with different themes write to :root', () => {
+      expect(() =>
+        render(
+          <React.Fragment>
+            <ThemeProvider theme={blueTheme}>
+              <div />
+            </ThemeProvider>
+            <ThemeProvider theme={redTheme}>
+              <div />
+            </ThemeProvider>
+          </React.Fragment>,
+        ),
+      ).toWarnDev('MUI: Several ThemeProviders with different themes write');
+    });
+  });
+
+  it('renders the `component` with the scope class', () => {
+    render(
+      <ThemeProvider theme={blueTheme}>
+        <ThemeProvider theme={redTheme} component="section" className="promo">
+          <div data-testid="inner" />
+        </ThemeProvider>
+      </ThemeProvider>,
+    );
+    const section = screen.getByTestId('inner').parentElement!;
+    expect(section.tagName).to.equal('SECTION');
+    expect(section.className).to.match(/^mui-theme-[a-z0-9]+ promo$/);
+    expect(section.style.display).to.equal('');
+  });
+
+  it('exposes the scope class to elements that are portaled by other libraries', () => {
+    function Scope() {
+      const props = useThemeScope();
+      return <div data-testid="scope" {...props} />;
+    }
+    render(
+      <ThemeProvider theme={blueTheme}>
+        <ThemeProvider theme={redTheme}>
+          <Scope />
+        </ThemeProvider>
+      </ThemeProvider>,
+    );
+    expect(screen.getByTestId('scope').className).to.equal(
+      screen.getByTestId('scope').parentElement!.className,
+    );
+  });
+});
diff --git a/packages/mui-material/src/styles/createThemeFoundation.ts b/packages/mui-material/src/styles/createThemeFoundation.ts
index 5583e386d9f7cd..84adde75ff1a18 100644
--- a/packages/mui-material/src/styles/createThemeFoundation.ts
+++ b/packages/mui-material/src/styles/createThemeFoundation.ts
@@ -421,6 +421,15 @@ export interface CssVarsTheme extends ColorSystem {
   getColorSchemeSelector: (colorScheme: SupportedColorScheme) => string;
   generateThemeVars: () => ThemeVars;
   generateStyleSheets: () => Array<Record<string, any>>;
+  /**
+   * @internal Used by ThemeProvider to scope the CSS theme variables of nested themes.
+   */
+  generateCssVarsByColorScheme?:
+    | (() => {
+        root: Record<string, string | number>;
+        colorSchemes: Array<[string, Record<string, string | number>]>;
+      })
+    | undefined;
   generateSpacing: () => SystemTheme['spacing'];
 
   // Default theme tokens
diff --git a/packages/mui-material/src/styles/createThemeWithVars.js b/packages/mui-material/src/styles/createThemeWithVars.js
index bd00b44d4c4ba7..84bac4ab98d64a 100644
--- a/packages/mui-material/src/styles/createThemeWithVars.js
+++ b/packages/mui-material/src/styles/createThemeWithVars.js
@@ -1010,13 +1010,15 @@ export default function createThemeWithVars(options = {}, ...args) {
     getSelector: defaultGetSelector(theme),
     enableContrastVars: nativeColor,
   };
-  const { vars, generateThemeVars, generateStyleSheets } = prepareCssVars(theme, parserConfig);
+  const { vars, generateThemeVars, generateStyleSheets, generateCssVarsByColorScheme } =
+    prepareCssVars(theme, parserConfig);
   theme.vars = vars;
   Object.entries(theme.colorSchemes[theme.defaultColorScheme]).forEach(([key, value]) => {
     theme[key] = value;
   });
   theme.generateThemeVars = generateThemeVars;
   theme.generateStyleSheets = generateStyleSheets;
+  theme.generateCssVarsByColorScheme = generateCssVarsByColorScheme;
   theme.generateSpacing = function generateSpacing() {
     return createSpacing(input.spacing, createUnarySpacing(this));
   };
diff --git a/packages/mui-material/src/styles/index.d.ts b/packages/mui-material/src/styles/index.d.ts
index d5c9d62233011d..2c2ff2eafe937b 100644
--- a/packages/mui-material/src/styles/index.d.ts
+++ b/packages/mui-material/src/styles/index.d.ts
@@ -127,7 +127,8 @@ export { default as withStyles } from './withStyles';
 export { default as withTheme } from './withTheme';
 
 export * from './ThemeProviderWithVars';
-export type { StorageManager } from '@mui/system/cssVars';
+export type { StorageManager, ThemeScopeProps } from '@mui/system/cssVars';
+export { useThemeScope } from '@mui/system/cssVars';
 
 export { default as extendTheme } from './createThemeWithVars';
 
diff --git a/packages/mui-material/src/styles/index.js b/packages/mui-material/src/styles/index.js
index 883093f0e1e25b..5c6a0660e0a34f 100644
--- a/packages/mui-material/src/styles/index.js
+++ b/packages/mui-material/src/styles/index.js
@@ -44,6 +44,7 @@ export { default as withStyles } from './withStyles';
 export { default as withTheme } from './withTheme';
 
 export * from './ThemeProviderWithVars';
+export { useThemeScope } from '@mui/system/cssVars';
 export { default as extendTheme } from './createThemeWithVars';
 export { default as experimental_extendTheme } from './experimental_extendTheme'; // TODO: Remove in v7
 export { default as getOverlayAlpha } from './getOverlayAlpha';
diff --git a/packages/mui-system/src/cssVars/ThemeScopeContext.ts b/packages/mui-system/src/cssVars/ThemeScopeContext.ts
new file mode 100644
index 00000000000000..a40521fcf66c2d
--- /dev/null
+++ b/packages/mui-system/src/cssVars/ThemeScopeContext.ts
@@ -0,0 +1,33 @@
+'use client';
+import * as React from 'react';
+
+export interface ThemeScopeProps {
+  /**
+   * The class that sets the CSS theme variables of the closest scoped `ThemeProvider`,
+   * followed by its color scheme class when its `colorSchemeSelector` is `'class'`.
+   */
+  className?: string | undefined;
+  /**
+   * Color scheme attributes, e.g. `data-mui-color-scheme`, when the `colorSchemeSelector` uses one.
+   */
+  [attribute: `data-${string}`]: string | undefined;
+}
+
+const ThemeScopeContext = React.createContext<ThemeScopeProps | undefined>(undefined);
+
+if (process.env.NODE_ENV !== 'production') {
+  ThemeScopeContext.displayName = 'ThemeScopeContext';
+}
+
+const emptyProps: ThemeScopeProps = {};
+
+/**
+ * Returns the props that apply the closest scoped `ThemeProvider` to an element.
+ * Portaled elements render outside the provider's element, so they need these props
+ * to use its CSS theme variables. Returns an empty object outside scoped providers.
+ */
+export function useThemeScope(): ThemeScopeProps {
+  return React.useContext(ThemeScopeContext) ?? emptyProps;
+}
+
+export default ThemeScopeContext;
diff --git a/packages/mui-system/src/cssVars/createCssVarsProvider.tsx b/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
index bfad6a75368bdd..cd0878d3a73ba6 100644
--- a/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
+++ b/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
@@ -1,6 +1,7 @@
 'use client';
 import * as React from 'react';
 import PropTypes from 'prop-types';
+import clsx from 'clsx';
 import { GlobalStyles } from '@mui/styled-engine';
 import { useTheme as muiUseTheme } from '@mui/private-theming';
 import useEnhancedEffect from '@mui/utils/useEnhancedEffect';
@@ -13,6 +14,13 @@ import {
 } from '../InitColorSchemeScript/InitColorSchemeScript';
 import useCurrentColorScheme, { type Result } from './useCurrentColorScheme';
 import type { StorageManager } from './localStorageManager';
+import ThemeScopeContext from './ThemeScopeContext';
+import {
+  createScopedStyleSheets,
+  getColorSchemeProps,
+  getColorSchemeRule,
+  type CssVarsByColorScheme,
+} from './scopeCssVars';
 
 export interface ColorSchemeContextValue<
   SupportedColorScheme extends string,
@@ -112,6 +120,24 @@ export interface CreateCssVarsProviderResult<
          * @default false
          */
         disableStyleSheetGeneration?: boolean | undefined;
+        /**
+         * If `true`, the CSS theme variables are set on an element that wraps the children instead of `:root`,
+         * so they don't affect the rest of the page. Use it for a provider that isn't nested in another one,
+         * like an embedded widget. Nested providers are scoped automatically when their variables differ.
+         *
+         * A string is used as a readable part of the class name, and to suffix the storage keys.
+         * @default false
+         */
+        scoped?: boolean | string | undefined;
+        /**
+         * The element that wraps the children of a scoped provider.
+         * By default, a `div` with `display: contents`.
+         */
+        component?: React.ElementType | undefined;
+        /**
+         * The class name of the element that wraps the children of a scoped provider.
+         */
+        className?: string | undefined;
       }
     >,
   ) => React.JSX.Element;
@@ -211,13 +237,19 @@ export default function createCssVarsProvider<
 
   const defaultColorSchemes = {};
   const defaultComponents = {};
+  const scopeStyle = { display: 'contents' };
+
+  // Stylesheets of the mounted providers that write to `:root`, to warn when they overwrite each other.
+  const rootStyleSheets: Map<string, string[]> = new Map();
+  let warnedMultipleRoots = false;
 
   function CssVarsProvider(props: any) {
     const {
       children,
       theme: themeProp,
-      modeStorageKey = defaultModeStorageKey,
-      colorSchemeStorageKey = defaultColorSchemeStorageKey,
+      scoped = false,
+      component,
+      className,
       disableTransitionOnChange = designSystemTransitionOnChange,
       storageManager,
       storageWindow = typeof window === 'undefined' ? undefined : window,
@@ -230,9 +262,18 @@ export default function createCssVarsProvider<
       noSsr,
     } = props;
     const hasMounted = React.useRef(false);
-    const upperTheme = muiUseTheme();
+    const upperTheme = muiUseTheme() as any;
     const ctx = React.useContext(ColorSchemeContext);
+    const upperScope = React.useContext(ThemeScopeContext);
     const nested = !!ctx && !disableNestedContext;
+    const scopeName = typeof scoped === 'string' ? scoped : undefined;
+    // A scoped provider that isn't nested manages its own color scheme on its element.
+    const isScopedRoot = !nested && !!scoped;
+    const storageKeySuffix = isScopedRoot && scopeName ? `-${scopeName}` : '';
+    const {
+      modeStorageKey = `${defaultModeStorageKey}${storageKeySuffix}`,
+      colorSchemeStorageKey = `${defaultColorSchemeStorageKey}${storageKeySuffix}`,
+    } = props;
 
     const initialTheme = React.useMemo(() => {
       if (themeProp) {
@@ -350,26 +391,18 @@ export default function createCssVarsProvider<
 
     // 5. Declaring effects
     // 5.1 Updates the selector value to use the current color scheme which tells CSS to use the proper stylesheet.
+    // A scoped root renders it on its own element instead.
     const colorSchemeSelector = restThemeProp.colorSchemeSelector;
+    const ownsColorSchemeNode = !isScopedRoot || props.colorSchemeNode !== undefined;
     useEnhancedEffect(() => {
       if (
+        ownsColorSchemeNode &&
         colorScheme &&
         colorSchemeNode &&
         colorSchemeSelector &&
         colorSchemeSelector !== 'media'
       ) {
-        const selector = colorSchemeSelector;
-        let rule = colorSchemeSelector;
-        if (selector === 'class') {
-          rule = `.%s`;
-        }
-        if (selector === 'data') {
-          rule = `[data-%s]`;
-        }
-        if (selector?.startsWith('data-') && !selector.includes('%s')) {
-          // 'data-mui-color-scheme' -> '[data-mui-color-scheme="%s"]'
-          rule = `[${selector}="%s"]`;
-        }
+        const rule = getColorSchemeRule(colorSchemeSelector)!;
         if (rule.startsWith('.')) {
           colorSchemeNode.classList.remove(
             ...allColorSchemes.map((scheme) => rule.substring(1).replace('%s', scheme)),
@@ -392,7 +425,7 @@ export default function createCssVarsProvider<
           }
         }
       }
-    }, [colorScheme, colorSchemeSelector, colorSchemeNode, allColorSchemes]);
+    }, [colorScheme, colorSchemeSelector, colorSchemeNode, allColorSchemes, ownsColorSchemeNode]);
 
     // 5.2 Remove the CSS transition when color scheme changes to create instant experience.
     // credit: https://github.com/pacocoursey/next-themes/blob/b5c2bad50de2d61ad7b52a9c5cdc801a78507d7a/index.tsx#L313
@@ -460,16 +493,105 @@ export default function createCssVarsProvider<
       ],
     );
 
-    let shouldGenerateStyleSheet = true;
-    if (
-      disableStyleSheetGeneration ||
-      restThemeProp.cssVariables === false ||
-      (nested && (upperTheme as any)?.cssVarPrefix === cssVarPrefix)
-    ) {
-      shouldGenerateStyleSheet = false;
+    const canGenerateStyleSheet =
+      !disableStyleSheetGeneration && restThemeProp.cssVariables !== false;
+    const samePrefixAsUpper = nested && upperTheme?.cssVarPrefix === cssVarPrefix;
+
+    // 6. Scope the CSS theme variables that can't go to `:root` to the provider's element.
+    const generateCssVarsByColorScheme: (() => CssVarsByColorScheme) | undefined =
+      restThemeProp.generateCssVarsByColorScheme;
+    const upperGenerateCssVarsByColorScheme: (() => CssVarsByColorScheme) | undefined =
+      samePrefixAsUpper ? upperTheme.generateCssVarsByColorScheme : undefined;
+    const upperColorSchemeSelector = nested ? upperTheme?.colorSchemeSelector : undefined;
+    const scope = React.useMemo(() => {
+      if (!canGenerateStyleSheet || !generateCssVarsByColorScheme) {
+        return null;
+      }
+      if (nested) {
+        // A nested theme with another prefix doesn't clash with the outer one, so it writes to `:root`.
+        if (!upperGenerateCssVarsByColorScheme) {
+          return null;
+        }
+        return createScopedStyleSheets({
+          css: generateCssVarsByColorScheme(),
+          upper: upperGenerateCssVarsByColorScheme(),
+          // It follows the outer color scheme.
+          colorSchemeSelector: upperColorSchemeSelector,
+          prefix: cssVarPrefix,
+          name: scopeName,
+        });
+      }
+      if (scoped) {
+        return createScopedStyleSheets({
+          css: generateCssVarsByColorScheme(),
+          colorSchemeSelector,
+          prefix: cssVarPrefix,
+          name: scopeName,
+        });
+      }
+      return null;
+    }, [
+      canGenerateStyleSheet,
+      generateCssVarsByColorScheme,
+      upperGenerateCssVarsByColorScheme,
+      upperColorSchemeSelector,
+      colorSchemeSelector,
+      cssVarPrefix,
+      nested,
+      scoped,
+      scopeName,
+    ]);
+
+    const scopeClassName = scope?.className;
+    const { className: colorSchemeClassName, ...colorSchemeAttributes } = isScopedRoot
+      ? getColorSchemeProps(colorSchemeSelector, colorScheme)
+      : ({} as Record<string, string>);
+    const colorSchemeAttributesKey = JSON.stringify(colorSchemeAttributes);
+    const scopeProps = React.useMemo(() => {
+      if (!scopeClassName) {
+        return undefined;
+      }
+      // Portaled elements aren't under the outer scopes' elements either, so they get them too.
+      return {
+        ...(nested ? upperScope : undefined),
+        ...JSON.parse(colorSchemeAttributesKey),
+        className: clsx(nested && upperScope?.className, scopeClassName, colorSchemeClassName),
+      };
+    }, [scopeClassName, colorSchemeClassName, colorSchemeAttributesKey, nested, upperScope]);
+
+    const shouldGenerateStyleSheet = canGenerateStyleSheet && !samePrefixAsUpper && !isScopedRoot;
+
+    if (process.env.NODE_ENV !== 'production') {
+      // eslint-disable-next-line react-hooks/rules-of-hooks
+      React.useEffect(() => {
+        if (!shouldGenerateStyleSheet || nested || !memoTheme.generateStyleSheets) {
+          return undefined;
+        }
+        const key = cssVarPrefix ?? '';
+        const styleSheet = JSON.stringify(memoTheme.generateStyleSheets());
+        const mounted = rootStyleSheets.get(key) ?? [];
+        rootStyleSheets.set(key, [...mounted, styleSheet]);
+        if (!warnedMultipleRoots && mounted.some((other) => other !== styleSheet)) {
+          warnedMultipleRoots = true;
+          console.warn(
+            [
+              'MUI: Several ThemeProviders with different themes write their CSS theme variables to `:root`, so they overwrite each other.',
+              'Add the `scoped` prop to the ThemeProviders that should only apply to their children, like an embedded widget.',
+            ].join('\n'),
+          );
+        }
+        return () => {
+          const current = rootStyleSheets.get(key) ?? [];
+          const index = current.indexOf(styleSheet);
+          rootStyleSheets.set(
+            key,
+            current.filter((_, i) => i !== index),
+          );
+        };
+      }, [shouldGenerateStyleSheet, nested, memoTheme, cssVarPrefix]);
     }
 
-    const element = (
+    let element = (
       <React.Fragment>
         <ThemeProvider themeId={scopedTheme ? themeId : undefined} theme={memoTheme}>
           {children}
@@ -480,6 +602,26 @@ export default function createCssVarsProvider<
       </React.Fragment>
     );
 
+    if (scope || component) {
+      const ScopeComponent = component || 'div';
+      element = (
+        <React.Fragment>
+          {scope && <GlobalStyles styles={scope.styles} />}
+          <ScopeComponent
+            {...colorSchemeAttributes}
+            className={clsx(scopeClassName, colorSchemeClassName, className) || undefined}
+            style={component ? undefined : scopeStyle}
+          >
+            {scopeProps ? (
+              <ThemeScopeContext.Provider value={scopeProps}>{element}</ThemeScopeContext.Provider>
+            ) : (
+              element
+            )}
+          </ScopeComponent>
+        </React.Fragment>
+      );
+    }
+
     if (nested) {
       return element;
     }
@@ -494,6 +636,10 @@ export default function createCssVarsProvider<
      * The component tree.
      */
     children: PropTypes.node,
+    /**
+     * The class name of the element that wraps the children of a scoped provider.
+     */
+    className: PropTypes.string,
     /**
      * The node used to attach the color-scheme attribute
      */
@@ -502,6 +648,10 @@ export default function createCssVarsProvider<
      * localStorage key used to store `colorScheme`
      */
     colorSchemeStorageKey: PropTypes.string,
+    /**
+     * The element that wraps the children of a scoped provider.
+     */
+    component: PropTypes.elementType,
     /**
      * The default mode when the storage is empty,
      * require the theme to have `colorSchemes` with light and dark.
@@ -543,6 +693,10 @@ export default function createCssVarsProvider<
      * @default using `window.localStorage`
      */
     storageManager: PropTypes.func,
+    /**
+     * If `true`, the CSS theme variables are set on an element that wraps the children instead of `:root`.
+     */
+    scoped: PropTypes.oneOfType([PropTypes.bool, PropTypes.string]),
     /**
      * The window that attaches the 'storage' event listener.
      * @default window
diff --git a/packages/mui-system/src/cssVars/createCssVarsTheme.ts b/packages/mui-system/src/cssVars/createCssVarsTheme.ts
index 03a5c73e7630d4..85139ea7da762e 100644
--- a/packages/mui-system/src/cssVars/createCssVarsTheme.ts
+++ b/packages/mui-system/src/cssVars/createCssVarsTheme.ts
@@ -25,6 +25,7 @@ function createCssVarsTheme<T extends Theme, ThemeVars extends Record<string, an
   output.vars = result.vars;
   output.generateThemeVars = result.generateThemeVars;
   output.generateStyleSheets = result.generateStyleSheets;
+  output.generateCssVarsByColorScheme = result.generateCssVarsByColorScheme;
   output.colorSchemeSelector = colorSchemeSelector;
   output.getColorSchemeSelector = createGetColorSchemeSelector(colorSchemeSelector);
   output.internal_cache = {};
diff --git a/packages/mui-system/src/cssVars/index.ts b/packages/mui-system/src/cssVars/index.ts
index 63df8b222a9817..9fc9a2259ec334 100644
--- a/packages/mui-system/src/cssVars/index.ts
+++ b/packages/mui-system/src/cssVars/index.ts
@@ -11,3 +11,5 @@ export type { ExtractTypographyTokens } from './prepareTypographyVars';
 export { default as createCssVarsTheme } from './createCssVarsTheme';
 export { createGetColorSchemeSelector } from './getColorSchemeSelector';
 export type { StorageManager } from './localStorageManager';
+export { useThemeScope } from './ThemeScopeContext';
+export type { ThemeScopeProps } from './ThemeScopeContext';
diff --git a/packages/mui-system/src/cssVars/prepareCssVars.ts b/packages/mui-system/src/cssVars/prepareCssVars.ts
index 8f85ee99119a6c..d82345d10c7b5d 100644
--- a/packages/mui-system/src/cssVars/prepareCssVars.ts
+++ b/packages/mui-system/src/cssVars/prepareCssVars.ts
@@ -1,6 +1,13 @@
 import deepmerge from '@mui/utils/deepmerge';
 import cssVarsParser from './cssVarsParser';
 
+// use double underscore to indicate that these are private variables
+const CONTRAST_VARS = {
+  '--__l-threshold': '0.7',
+  '--__l': 'clamp(0, (l / var(--__l-threshold) - 1) * -infinity, 1)',
+  '--__a': 'clamp(0.87, (l / var(--__l-threshold) - 1) * -infinity, 1)', // 0.87 is the default alpha value for black text.
+};
+
 export interface DefaultCssVarsTheme {
   colorSchemes?: Record<string, any> | undefined;
   defaultColorScheme?: string | undefined;
@@ -98,9 +105,34 @@ function prepareCssVars<T extends DefaultCssVarsTheme, ThemeVars extends Record<
     return vars;
   };
 
+  /**
+   * Returns the CSS declarations of the theme before they are assigned to selectors:
+   * the ones shared by all color schemes, and the ones of each color scheme, default first.
+   */
+  const generateCssVarsByColorScheme = () => {
+    const colorScheme = theme.defaultColorScheme || 'light';
+    const schemes: Array<[string, Record<string, string | number>]> = [];
+    const { [colorScheme]: defaultSchemeVal, ...other } = colorSchemesMap;
+    const entries = defaultSchemeVal
+      ? [[colorScheme, defaultSchemeVal] as const, ...Object.entries(other)]
+      : Object.entries(other);
+    entries.forEach(([key, { css }]) => {
+      const cssColorSheme = colorSchemes[key]?.palette?.mode;
+      schemes.push([
+        key,
+        !disableCssColorScheme && cssColorSheme
+          ? { colorScheme: cssColorSheme, ...css }
+          : { ...css },
+      ]);
+    });
+    return {
+      root: enableContrastVars ? { ...rootCss, ...CONTRAST_VARS } : { ...rootCss },
+      colorSchemes: schemes,
+    };
+  };
+
   const generateStyleSheets = () => {
     const stylesheets: Array<Record<string, any>> = [];
-    const colorScheme = theme.defaultColorScheme || 'light';
     function insertStyleSheet(key: string | object, css: Record<string, string | number>) {
       if (Object.keys(css).length) {
         stylesheets.push(typeof key === 'string' ? { [key]: { ...css } } : key);
@@ -108,40 +140,13 @@ function prepareCssVars<T extends DefaultCssVarsTheme, ThemeVars extends Record<
     }
     insertStyleSheet(getSelector(undefined, { ...rootCss }), rootCss);
 
-    const { [colorScheme]: defaultSchemeVal, ...other } = colorSchemesMap;
-
-    if (defaultSchemeVal) {
-      // default color scheme has to come before other color schemes
-      const { css } = defaultSchemeVal;
-      const cssColorSheme = colorSchemes[colorScheme]?.palette?.mode;
-      const finalCss =
-        !disableCssColorScheme && cssColorSheme
-          ? { colorScheme: cssColorSheme, ...css }
-          : { ...css };
-      insertStyleSheet(
-        getSelector(colorScheme as keyof T['colorSchemes'], { ...finalCss }),
-        finalCss,
-      );
-    }
-
-    Object.entries(other).forEach(([key, { css }]) => {
-      const cssColorSheme = colorSchemes[key]?.palette?.mode;
-      const finalCss =
-        !disableCssColorScheme && cssColorSheme
-          ? { colorScheme: cssColorSheme, ...css }
-          : { ...css };
+    // default color scheme has to come before other color schemes
+    generateCssVarsByColorScheme().colorSchemes.forEach(([key, finalCss]) => {
       insertStyleSheet(getSelector(key as keyof T['colorSchemes'], { ...finalCss }), finalCss);
     });
 
     if (enableContrastVars) {
-      stylesheets.push({
-        ':root': {
-          // use double underscore to indicate that these are private variables
-          '--__l-threshold': '0.7',
-          '--__l': 'clamp(0, (l / var(--__l-threshold) - 1) * -infinity, 1)',
-          '--__a': 'clamp(0.87, (l / var(--__l-threshold) - 1) * -infinity, 1)', // 0.87 is the default alpha value for black text.
-        },
-      });
+      stylesheets.push({ ':root': { ...CONTRAST_VARS } });
     }
 
     return stylesheets;
@@ -151,6 +156,7 @@ function prepareCssVars<T extends DefaultCssVarsTheme, ThemeVars extends Record<
     vars: themeVars,
     generateThemeVars,
     generateStyleSheets,
+    generateCssVarsByColorScheme,
   };
 }
 
diff --git a/packages/mui-system/src/cssVars/scopeCssVars.test.ts b/packages/mui-system/src/cssVars/scopeCssVars.test.ts
new file mode 100644
index 00000000000000..bf893b6b6368fb
--- /dev/null
+++ b/packages/mui-system/src/cssVars/scopeCssVars.test.ts
@@ -0,0 +1,117 @@
+import { describe, it, expect } from 'vitest';
+import { createScopedStyleSheets, getColorSchemeProps } from './scopeCssVars';
+
+const upper = {
+  root: { '--mui-spacing': '8px' },
+  colorSchemes: [
+    ['light', { colorScheme: 'light', '--mui-primary': 'blue', '--mui-text': 'black' }],
+    ['dark', { colorScheme: 'dark', '--mui-primary': 'lightblue', '--mui-text': 'white' }],
+  ] as Array<[string, Record<string, string>]>,
+};
+
+describe('createScopedStyleSheets', () => {
+  it('returns null when a nested theme has the same declarations', () => {
+    expect(
+      createScopedStyleSheets({ css: upper, upper, colorSchemeSelector: 'class', prefix: 'mui' }),
+    ).to.equal(null);
+  });
+
+  it('writes only the declarations that differ from the outer theme', () => {
+    const result = createScopedStyleSheets({
+      css: {
+        root: { '--mui-spacing': '8px' },
+        colorSchemes: [
+          ['light', { colorScheme: 'light', '--mui-primary': 'red', '--mui-text': 'black' }],
+          ['dark', { colorScheme: 'dark', '--mui-primary': 'pink', '--mui-text': 'white' }],
+        ],
+      },
+      upper,
+      colorSchemeSelector: 'class',
+      prefix: 'mui',
+    })!;
+    const scope = `.${result.className}`;
+    expect(result.className).to.match(/^mui-theme-[a-z0-9]+$/);
+    expect(result.styles).to.deep.equal([
+      { [scope]: { '--mui-primary': 'red' } },
+      { [`.dark ${scope}, ${scope}.dark`]: { '--mui-primary': 'pink' } },
+    ]);
+  });
+
+  it('writes the default color scheme declarations again for the other color schemes', () => {
+    // Only the light primary changes, but `.scope` applies in dark mode too.
+    const result = createScopedStyleSheets({
+      css: {
+        root: upper.root,
+        colorSchemes: [
+          ['light', { ...upper.colorSchemes[0][1], '--mui-primary': 'red' }],
+          upper.colorSchemes[1],
+        ],
+      },
+      upper,
+      colorSchemeSelector: 'class',
+      prefix: 'mui',
+    })!;
+    const scope = `.${result.className}`;
+    expect(result.styles).to.deep.equal([
+      { [scope]: { '--mui-primary': 'red' } },
+      { [`.dark ${scope}, ${scope}.dark`]: { '--mui-primary': 'lightblue' } },
+    ]);
+  });
+
+  it('writes a single color scheme in full, whatever the outer color scheme is', () => {
+    const result = createScopedStyleSheets({
+      css: { root: upper.root, colorSchemes: [upper.colorSchemes[1]] },
+      upper,
+      colorSchemeSelector: 'class',
+      prefix: 'mui',
+    })!;
+    expect(result.styles).to.deep.equal([{ [`.${result.className}`]: upper.colorSchemes[1][1] }]);
+  });
+
+  it('uses media queries with the media selector', () => {
+    const result = createScopedStyleSheets({
+      css: upper,
+      colorSchemeSelector: 'media',
+      prefix: 'mui',
+    })!;
+    const scope = `.${result.className}`;
+    expect(result.styles).to.deep.equal([
+      { [scope]: upper.root },
+      { [scope]: upper.colorSchemes[0][1] },
+      { '@media (prefers-color-scheme: dark)': { [scope]: upper.colorSchemes[1][1] } },
+    ]);
+  });
+
+  it('puts the color scheme rule on the scoped element when it is not nested', () => {
+    const result = createScopedStyleSheets({
+      css: upper,
+      colorSchemeSelector: 'data-mui-color-scheme',
+      prefix: 'mui',
+      name: 'widget',
+    })!;
+    const scope = `.${result.className}`;
+    expect(result.className).to.match(/^mui-theme-widget-[a-z0-9]+$/);
+    expect(result.styles[2]).to.deep.equal({
+      [`${scope}[data-mui-color-scheme="dark"]`]: upper.colorSchemes[1][1],
+    });
+  });
+
+  it('gives the same class name to the same declarations', () => {
+    const options = { css: upper, colorSchemeSelector: 'class', prefix: 'mui' };
+    expect(createScopedStyleSheets(options)!.className).to.equal(
+      createScopedStyleSheets({ ...options, css: structuredClone(upper) })!.className,
+    );
+  });
+});
+
+describe('getColorSchemeProps', () => {
+  it('returns the class or attribute of a color scheme', () => {
+    expect(getColorSchemeProps('class', 'dark')).to.deep.equal({ className: 'dark' });
+    expect(getColorSchemeProps('data', 'dark')).to.deep.equal({ 'data-dark': '' });
+    expect(getColorSchemeProps('data-mui-color-scheme', 'dark')).to.deep.equal({
+      'data-mui-color-scheme': 'dark',
+    });
+    expect(getColorSchemeProps('media', 'dark')).to.deep.equal({});
+    expect(getColorSchemeProps('class', undefined)).to.deep.equal({});
+  });
+});
diff --git a/packages/mui-system/src/cssVars/scopeCssVars.ts b/packages/mui-system/src/cssVars/scopeCssVars.ts
new file mode 100644
index 00000000000000..e7e4b0a3145fc9
--- /dev/null
+++ b/packages/mui-system/src/cssVars/scopeCssVars.ts
@@ -0,0 +1,163 @@
+type CssDeclarations = Record<string, string | number>;
+
+export interface CssVarsByColorScheme {
+  root: CssDeclarations;
+  colorSchemes: Array<[string, CssDeclarations]>;
+}
+
+/**
+ * Turns `theme.colorSchemeSelector` into a rule with a `%s` placeholder for the color scheme,
+ * or `'media'`. Returns `undefined` when there's no selector.
+ */
+export function getColorSchemeRule(selector: string | undefined) {
+  if (selector === 'class') {
+    return '.%s';
+  }
+  if (selector === 'data') {
+    return '[data-%s]';
+  }
+  if (selector?.startsWith('data-') && !selector.includes('%s')) {
+    // 'data-mui-color-scheme' -> '[data-mui-color-scheme="%s"]'
+    return `[${selector}="%s"]`;
+  }
+  return selector;
+}
+
+/**
+ * Returns the props that make an element match the color scheme rule,
+ * e.g. `{ className: 'dark' }` for `.%s` or `{ 'data-mui-color-scheme': 'dark' }`.
+ */
+export function getColorSchemeProps(
+  selector: string | undefined,
+  colorScheme: string | undefined,
+): Record<string, string> {
+  const rule = getColorSchemeRule(selector);
+  if (!rule || rule === 'media' || !colorScheme) {
+    return {};
+  }
+  if (rule.startsWith('.')) {
+    return { className: rule.substring(1).replace('%s', colorScheme) };
+  }
+  const matches = rule.replace('%s', colorScheme).match(/\[([^\]]+)\]/);
+  if (!matches) {
+    return {};
+  }
+  const [attr, value] = matches[1].split('=');
+  return { [attr]: value ? value.replace(/"|'/g, '') : '' };
+}
+
+// FNV-1a, enough to give each set of declarations a short and stable class name.
+/* eslint-disable no-bitwise */
+function hash(value: string) {
+  let result = 0x811c9dc5;
+  for (let i = 0; i < value.length; i += 1) {
+    result ^= value.charCodeAt(i);
+    result = Math.imul(result, 0x01000193);
+  }
+  return (result >>> 0).toString(36);
+}
+/* eslint-enable no-bitwise */
+
+function pickChanged(css: CssDeclarations, upperCss: CssDeclarations | undefined) {
+  if (!upperCss) {
+    return { ...css };
+  }
+  const result: CssDeclarations = {};
+  Object.keys(css).forEach((key) => {
+    if (css[key] !== upperCss[key]) {
+      result[key] = css[key];
+    }
+  });
+  return result;
+}
+
+/**
+ * Builds the stylesheets that set the CSS theme variables of a theme on a class instead of `:root`,
+ * so that only the elements under that class use them.
+ *
+ * - With `upper`, the theme is nested: only the declarations that differ from `upper` are written,
+ *   and the color scheme follows the outer provider, whose rule is on an ancestor (`.dark .scope`)
+ *   or, for portaled elements, on the same element (`.scope.dark`).
+ * - Without `upper`, all declarations are written, and the color scheme rule is on the scoped element
+ *   itself (`.scope.dark`), since the provider manages its own color scheme.
+ *
+ * Returns `null` when there's nothing to write.
+ */
+export function createScopedStyleSheets(options: {
+  css: CssVarsByColorScheme;
+  upper?: CssVarsByColorScheme | undefined;
+  colorSchemeSelector: string | undefined;
+  prefix: string;
+  name?: string | undefined;
+}) {
+  const { css, upper, colorSchemeSelector, prefix, name } = options;
+  const rule = getColorSchemeRule(colorSchemeSelector);
+  const [defaultScheme, ...otherSchemes] = css.colorSchemes;
+  const upperSchemes = upper ? Object.fromEntries(upper.colorSchemes) : {};
+  // A theme with a single color scheme uses it whatever the outer color scheme is,
+  // so unless the outer theme has a single color scheme too, it's written in full.
+  const isForcedScheme = css.colorSchemes.length === 1 && (upper?.colorSchemes.length ?? 0) > 1;
+
+  const root = pickChanged(css.root, upper?.root);
+  const schemes: Array<[string, CssDeclarations]> = [];
+  if (defaultScheme) {
+    const [key, declarations] = defaultScheme;
+    const changed = pickChanged(declarations, isForcedScheme ? undefined : upperSchemes[key]);
+    schemes.push([key, changed]);
+    otherSchemes.forEach(([otherKey, otherDeclarations]) => {
+      const otherChanged = pickChanged(otherDeclarations, upperSchemes[otherKey]);
+      // The default color scheme's rule applies in every color scheme, so each declaration
+      // it writes has to be written again for the other color schemes.
+      Object.keys(changed).forEach((declaration) => {
+        if (declaration in otherDeclarations) {
+          otherChanged[declaration] = otherDeclarations[declaration];
+        }
+      });
+      schemes.push([otherKey, otherChanged]);
+    });
+  }
+
+  const isEmpty =
+    Object.keys(root).length === 0 &&
+    schemes.every(([, declarations]) => Object.keys(declarations).length === 0);
+  if (isEmpty) {
+    return null;
+  }
+
+  const className = `${prefix ? `${prefix}-` : ''}theme-${name ? `${name}-` : ''}${hash(
+    JSON.stringify([root, schemes, rule, !!upper]),
+  )}`;
+  const scope = `.${className}`;
+
+  function getSelector(colorScheme: string) {
+    if (!rule) {
+      return scope;
+    }
+    const colorSchemeRule = rule.replace('%s', colorScheme);
+    // A portaled element gets the outer scopes' classes too, so the color scheme rule
+    // can also be on the scoped element itself.
+    return upper
+      ? `${colorSchemeRule} ${scope}, ${scope}${colorSchemeRule}`
+      : `${scope}${colorSchemeRule}`;
+  }
+
+  const styles: Array<Record<string, any>> = [];
+  if (Object.keys(root).length) {
+    styles.push({ [scope]: root });
+  }
+  schemes.forEach(([key, declarations], index) => {
+    if (!Object.keys(declarations).length) {
+      return;
+    }
+    if (index === 0) {
+      styles.push({ [scope]: declarations });
+    } else if (rule === 'media') {
+      const mode = Object.fromEntries(css.colorSchemes)[key].colorScheme || key;
+      styles.push({ [`@media (prefers-color-scheme: ${mode})`]: { [scope]: declarations } });
+    } else {
+      styles.push({ [getSelector(key)]: declarations });
+    }
+  });
+
+  return { className, styles };
+}

From b8da872ed1a3122b207568dabe687fbd3cc89117 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 26 Oct 2026 10:48:29 +0000
Subject: [PATCH 02/20] [docs] Document nested and scoped ThemeProviders with
 CSS theme variables

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HG4YYGmgsLG7riohZnG1WZ
---
 .../css-theme-variables/configuration.md      | 72 +++++++++++++++++++
 .../material/customization/theming/theming.md |  3 +
 2 files changed, 75 insertions(+)

diff --git a/docs/data/material/customization/css-theme-variables/configuration.md b/docs/data/material/customization/css-theme-variables/configuration.md
index af198b2064d4ae..bf425659ddbb84 100644
--- a/docs/data/material/customization/css-theme-variables/configuration.md
+++ b/docs/data/material/customization/css-theme-variables/configuration.md
@@ -277,6 +277,78 @@ In the example below, all the components inside the `div` will always be dark:
 
 </codeblock>
 
+## Nested and multiple theme providers
+
+The first `ThemeProvider` writes the CSS theme variables to `:root`, so they apply to the whole page.
+Any other provider writes the same variables on an element that wraps its children, so they only apply there.
+
+### Nested providers
+
+A nested `ThemeProvider` whose variables differ from the outer theme wraps its children in a `div` with `display: contents` and a generated class.
+The class only sets the variables that differ, and it follows the outer light or dark mode:
+
+```jsx
+<ThemeProvider theme={appTheme}>
+  <Button>Uses appTheme</Button>
+  <ThemeProvider theme={promoTheme}>
+    <Button>Uses promoTheme</Button>
+  </ThemeProvider>
+</ThemeProvider>
+```
+
+```css
+:root {
+  --mui-palette-primary-main: #1976d2;
+}
+.mui-theme-1x2y3z {
+  --mui-palette-primary-main: #9c27b0;
+}
+```
+
+A nested provider with the same variables, for example one that only changes `components` defaults, renders no element.
+
+Dialogs, menus, popovers, tooltips, and other components that render in a portal apply the class to their own root, so they use the nested theme too.
+For elements that other libraries portal, use the `useThemeScope()` hook to get the class:
+
+```jsx
+import { useThemeScope } from '@mui/material/styles';
+
+function Toast() {
+  const themeScope = useThemeScope();
+  return ReactDOM.createPortal(<div {...themeScope}>…</div>, document.body);
+}
+```
+
+To put the class on your own element instead of the `div`, for example inside a table or a list, where a `div` isn't valid HTML, use the `component` prop:
+
+```jsx
+<ThemeProvider theme={promoTheme} component="tbody" className="promo">
+  {rows}
+</ThemeProvider>
+```
+
+### Sibling providers
+
+A `ThemeProvider` that isn't nested in another one also writes to `:root`, so two of them overwrite each other.
+Add the `scoped` prop to the one that should only apply to its children, like an embedded widget:
+
+```jsx
+<ThemeProvider theme={appTheme}>
+  <App />
+</ThemeProvider>
+<ThemeProvider theme={widgetTheme} scoped="widget">
+  <Widget />
+</ThemeProvider>
+```
+
+A scoped provider writes all of its variables on its element, and has its own light or dark mode.
+When `scoped` is a string, it's added to the class name and to the storage keys of the mode, for example `mui-mode-widget`.
+
+:::info
+A CSS variable that you override on `:root` doesn't reach the elements under a scoped provider that sets it, because the closest declaration wins.
+Override it on the scoped element instead, for example with the `className` prop.
+:::
+
 ## Disabling CSS color scheme
 
 By default, `createTheme()` attaches a [CSS `color-scheme` property](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme) based on the palette mode.
diff --git a/docs/data/material/customization/theming/theming.md b/docs/data/material/customization/theming/theming.md
index 5e3481df0516ce..3c657097ea1c78 100644
--- a/docs/data/material/customization/theming/theming.md
+++ b/docs/data/material/customization/theming/theming.md
@@ -125,6 +125,9 @@ You can extend the outer theme by providing a function:
 
 {{"component": "file://./demos/theme-nesting-extend/index.ts"}}
 
+With CSS theme variables, a nested theme sets its variables on an element that wraps its children.
+See [Nested and multiple theme providers](/material-ui/customization/css-theme-variables/configuration/#nested-and-multiple-theme-providers) for details.
+
 ## CSS theme variables
 
 To generate CSS variables from the theme, set `cssVariables` to `true` in the theme configuration and pass it to the `ThemeProvider`:

From 39577d074533bd807a4900519732e4b87faa7166 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Mon, 26 Oct 2026 14:56:08 +0100
Subject: [PATCH 03/20] [docs][system] Polish the scoped ThemeProvider docs and
 drop an unneeded type

- Fix the intro of "Nested and multiple theme providers": sibling providers also write to `:root`, only nested or `scoped` ones are scoped.
- Mention the dev warning for sibling providers, and that a `scoped` name suffixes both storage keys.
- Note in the theming guide that only nested themes whose variables differ are wrapped.
- Remove the internal `generateCssVarsByColorScheme` type from `CssVarsTheme`; it's only read through untyped code.
- Sort the `scoped` propType alphabetically.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../customization/css-theme-variables/configuration.md   | 8 ++++----
 docs/data/material/customization/theming/theming.md      | 2 +-
 .../mui-material/src/styles/createThemeFoundation.ts     | 9 ---------
 .../mui-system/src/cssVars/createCssVarsProvider.tsx     | 8 ++++----
 4 files changed, 9 insertions(+), 18 deletions(-)

diff --git a/docs/data/material/customization/css-theme-variables/configuration.md b/docs/data/material/customization/css-theme-variables/configuration.md
index bf425659ddbb84..69cace591304b6 100644
--- a/docs/data/material/customization/css-theme-variables/configuration.md
+++ b/docs/data/material/customization/css-theme-variables/configuration.md
@@ -279,8 +279,8 @@ In the example below, all the components inside the `div` will always be dark:
 
 ## Nested and multiple theme providers
 
-The first `ThemeProvider` writes the CSS theme variables to `:root`, so they apply to the whole page.
-Any other provider writes the same variables on an element that wraps its children, so they only apply there.
+A `ThemeProvider` writes the CSS theme variables to `:root`, so they apply to the whole page.
+A nested or `scoped` provider writes them on an element that wraps its children instead, so they only apply there.
 
 ### Nested providers
 
@@ -329,7 +329,7 @@ To put the class on your own element instead of the `div`, for example inside a
 
 ### Sibling providers
 
-A `ThemeProvider` that isn't nested in another one also writes to `:root`, so two of them overwrite each other.
+Two `ThemeProvider`s that aren't nested in each other both write to `:root` and overwrite each other, which logs a warning in development.
 Add the `scoped` prop to the one that should only apply to its children, like an embedded widget:
 
 ```jsx
@@ -342,7 +342,7 @@ Add the `scoped` prop to the one that should only apply to its children, like an
 ```
 
 A scoped provider writes all of its variables on its element, and has its own light or dark mode.
-When `scoped` is a string, it's added to the class name and to the storage keys of the mode, for example `mui-mode-widget`.
+When `scoped` is a string, it's added to the class name and to the storage keys of the mode and color scheme, for example `mui-mode-widget`.
 
 :::info
 A CSS variable that you override on `:root` doesn't reach the elements under a scoped provider that sets it, because the closest declaration wins.
diff --git a/docs/data/material/customization/theming/theming.md b/docs/data/material/customization/theming/theming.md
index 3c657097ea1c78..d15068a075f890 100644
--- a/docs/data/material/customization/theming/theming.md
+++ b/docs/data/material/customization/theming/theming.md
@@ -125,7 +125,7 @@ You can extend the outer theme by providing a function:
 
 {{"component": "file://./demos/theme-nesting-extend/index.ts"}}
 
-With CSS theme variables, a nested theme sets its variables on an element that wraps its children.
+With CSS theme variables, a nested theme whose variables differ from the outer theme sets them on an element that wraps its children.
 See [Nested and multiple theme providers](/material-ui/customization/css-theme-variables/configuration/#nested-and-multiple-theme-providers) for details.
 
 ## CSS theme variables
diff --git a/packages/mui-material/src/styles/createThemeFoundation.ts b/packages/mui-material/src/styles/createThemeFoundation.ts
index 84adde75ff1a18..5583e386d9f7cd 100644
--- a/packages/mui-material/src/styles/createThemeFoundation.ts
+++ b/packages/mui-material/src/styles/createThemeFoundation.ts
@@ -421,15 +421,6 @@ export interface CssVarsTheme extends ColorSystem {
   getColorSchemeSelector: (colorScheme: SupportedColorScheme) => string;
   generateThemeVars: () => ThemeVars;
   generateStyleSheets: () => Array<Record<string, any>>;
-  /**
-   * @internal Used by ThemeProvider to scope the CSS theme variables of nested themes.
-   */
-  generateCssVarsByColorScheme?:
-    | (() => {
-        root: Record<string, string | number>;
-        colorSchemes: Array<[string, Record<string, string | number>]>;
-      })
-    | undefined;
   generateSpacing: () => SystemTheme['spacing'];
 
   // Default theme tokens
diff --git a/packages/mui-system/src/cssVars/createCssVarsProvider.tsx b/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
index cd0878d3a73ba6..ec0691a22630ba 100644
--- a/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
+++ b/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
@@ -688,15 +688,15 @@ export default function createCssVarsProvider<
      * You should use this option in conjunction with `InitColorSchemeScript` component.
      */
     noSsr: PropTypes.bool,
+    /**
+     * If `true`, the CSS theme variables are set on an element that wraps the children instead of `:root`.
+     */
+    scoped: PropTypes.oneOfType([PropTypes.bool, PropTypes.string]),
     /**
      * The storage manager to be used for storing the mode and color scheme
      * @default using `window.localStorage`
      */
     storageManager: PropTypes.func,
-    /**
-     * If `true`, the CSS theme variables are set on an element that wraps the children instead of `:root`.
-     */
-    scoped: PropTypes.oneOfType([PropTypes.bool, PropTypes.string]),
     /**
      * The window that attaches the 'storage' event listener.
      * @default window

From 408e75d418432515e0fb12a9bde5b1662ed73798 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Mon, 26 Oct 2026 15:01:25 +0100
Subject: [PATCH 04/20] [system] Avoid unrelated refactors in the CSS variables
 provider

Keep `generateStyleSheets` and the color scheme selector effect as they are on master. `generateCssVarsByColorScheme` and `getColorSchemeRule` are now only used for scoping.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../src/cssVars/createCssVarsProvider.tsx     | 14 +++++++++--
 .../mui-system/src/cssVars/prepareCssVars.ts  | 25 +++++++++++++++++--
 .../mui-system/src/cssVars/scopeCssVars.ts    |  2 +-
 3 files changed, 36 insertions(+), 5 deletions(-)

diff --git a/packages/mui-system/src/cssVars/createCssVarsProvider.tsx b/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
index ec0691a22630ba..036a3e563e1a88 100644
--- a/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
+++ b/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
@@ -18,7 +18,6 @@ import ThemeScopeContext from './ThemeScopeContext';
 import {
   createScopedStyleSheets,
   getColorSchemeProps,
-  getColorSchemeRule,
   type CssVarsByColorScheme,
 } from './scopeCssVars';
 
@@ -402,7 +401,18 @@ export default function createCssVarsProvider<
         colorSchemeSelector &&
         colorSchemeSelector !== 'media'
       ) {
-        const rule = getColorSchemeRule(colorSchemeSelector)!;
+        const selector = colorSchemeSelector;
+        let rule = colorSchemeSelector;
+        if (selector === 'class') {
+          rule = `.%s`;
+        }
+        if (selector === 'data') {
+          rule = `[data-%s]`;
+        }
+        if (selector?.startsWith('data-') && !selector.includes('%s')) {
+          // 'data-mui-color-scheme' -> '[data-mui-color-scheme="%s"]'
+          rule = `[${selector}="%s"]`;
+        }
         if (rule.startsWith('.')) {
           colorSchemeNode.classList.remove(
             ...allColorSchemes.map((scheme) => rule.substring(1).replace('%s', scheme)),
diff --git a/packages/mui-system/src/cssVars/prepareCssVars.ts b/packages/mui-system/src/cssVars/prepareCssVars.ts
index d82345d10c7b5d..d71f0d223971da 100644
--- a/packages/mui-system/src/cssVars/prepareCssVars.ts
+++ b/packages/mui-system/src/cssVars/prepareCssVars.ts
@@ -133,6 +133,7 @@ function prepareCssVars<T extends DefaultCssVarsTheme, ThemeVars extends Record<
 
   const generateStyleSheets = () => {
     const stylesheets: Array<Record<string, any>> = [];
+    const colorScheme = theme.defaultColorScheme || 'light';
     function insertStyleSheet(key: string | object, css: Record<string, string | number>) {
       if (Object.keys(css).length) {
         stylesheets.push(typeof key === 'string' ? { [key]: { ...css } } : key);
@@ -140,8 +141,28 @@ function prepareCssVars<T extends DefaultCssVarsTheme, ThemeVars extends Record<
     }
     insertStyleSheet(getSelector(undefined, { ...rootCss }), rootCss);
 
-    // default color scheme has to come before other color schemes
-    generateCssVarsByColorScheme().colorSchemes.forEach(([key, finalCss]) => {
+    const { [colorScheme]: defaultSchemeVal, ...other } = colorSchemesMap;
+
+    if (defaultSchemeVal) {
+      // default color scheme has to come before other color schemes
+      const { css } = defaultSchemeVal;
+      const cssColorSheme = colorSchemes[colorScheme]?.palette?.mode;
+      const finalCss =
+        !disableCssColorScheme && cssColorSheme
+          ? { colorScheme: cssColorSheme, ...css }
+          : { ...css };
+      insertStyleSheet(
+        getSelector(colorScheme as keyof T['colorSchemes'], { ...finalCss }),
+        finalCss,
+      );
+    }
+
+    Object.entries(other).forEach(([key, { css }]) => {
+      const cssColorSheme = colorSchemes[key]?.palette?.mode;
+      const finalCss =
+        !disableCssColorScheme && cssColorSheme
+          ? { colorScheme: cssColorSheme, ...css }
+          : { ...css };
       insertStyleSheet(getSelector(key as keyof T['colorSchemes'], { ...finalCss }), finalCss);
     });
 
diff --git a/packages/mui-system/src/cssVars/scopeCssVars.ts b/packages/mui-system/src/cssVars/scopeCssVars.ts
index e7e4b0a3145fc9..9d15c0dac1b128 100644
--- a/packages/mui-system/src/cssVars/scopeCssVars.ts
+++ b/packages/mui-system/src/cssVars/scopeCssVars.ts
@@ -9,7 +9,7 @@ export interface CssVarsByColorScheme {
  * Turns `theme.colorSchemeSelector` into a rule with a `%s` placeholder for the color scheme,
  * or `'media'`. Returns `undefined` when there's no selector.
  */
-export function getColorSchemeRule(selector: string | undefined) {
+function getColorSchemeRule(selector: string | undefined) {
   if (selector === 'class') {
     return '.%s';
   }

From 6929aa36e0c9aa90dbe12296fd569dd16b6a33a3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Mon, 26 Oct 2026 15:07:19 +0100
Subject: [PATCH 05/20] [system] Create the scoped stylesheets once per pair of
 themes

Every nested provider generated and diffed the CSS variables of both themes on mount, which made 100 nested providers mount about 33% slower than on master. The result only depends on the themes, so cache it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../src/cssVars/createCssVarsProvider.tsx     | 68 +++++++++++++++----
 1 file changed, 55 insertions(+), 13 deletions(-)

diff --git a/packages/mui-system/src/cssVars/createCssVarsProvider.tsx b/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
index 036a3e563e1a88..81e8b5de5d5341 100644
--- a/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
+++ b/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
@@ -238,6 +238,47 @@ export default function createCssVarsProvider<
   const defaultComponents = {};
   const scopeStyle = { display: 'contents' };
 
+  // The scoped stylesheets only depend on the themes, so they're created once per pair of themes
+  // instead of once per provider.
+  type ScopedStyleSheets = ReturnType<typeof createScopedStyleSheets>;
+  const scopedStyleSheetsCache: WeakMap<
+    () => CssVarsByColorScheme,
+    WeakMap<object, Map<string, ScopedStyleSheets>>
+  > = new WeakMap();
+  const noUpper = {};
+  function getScopedStyleSheets(
+    generate: () => CssVarsByColorScheme,
+    upperGenerate: (() => CssVarsByColorScheme) | undefined,
+    colorSchemeSelector: string | undefined,
+    prefix: string,
+    name: string | undefined,
+  ) {
+    let byUpper = scopedStyleSheetsCache.get(generate);
+    if (!byUpper) {
+      byUpper = new WeakMap();
+      scopedStyleSheetsCache.set(generate, byUpper);
+    }
+    let byOptions = byUpper.get(upperGenerate ?? noUpper);
+    if (!byOptions) {
+      byOptions = new Map();
+      byUpper.set(upperGenerate ?? noUpper, byOptions);
+    }
+    const key = `${colorSchemeSelector}|${prefix}|${name}`;
+    if (!byOptions.has(key)) {
+      byOptions.set(
+        key,
+        createScopedStyleSheets({
+          css: generate(),
+          upper: upperGenerate?.(),
+          colorSchemeSelector,
+          prefix,
+          name,
+        }),
+      );
+    }
+    return byOptions.get(key) as ScopedStyleSheets;
+  }
+
   // Stylesheets of the mounted providers that write to `:root`, to warn when they overwrite each other.
   const rootStyleSheets: Map<string, string[]> = new Map();
   let warnedMultipleRoots = false;
@@ -522,22 +563,23 @@ export default function createCssVarsProvider<
         if (!upperGenerateCssVarsByColorScheme) {
           return null;
         }
-        return createScopedStyleSheets({
-          css: generateCssVarsByColorScheme(),
-          upper: upperGenerateCssVarsByColorScheme(),
-          // It follows the outer color scheme.
-          colorSchemeSelector: upperColorSchemeSelector,
-          prefix: cssVarPrefix,
-          name: scopeName,
-        });
+        // It follows the outer color scheme.
+        return getScopedStyleSheets(
+          generateCssVarsByColorScheme,
+          upperGenerateCssVarsByColorScheme,
+          upperColorSchemeSelector,
+          cssVarPrefix,
+          scopeName,
+        );
       }
       if (scoped) {
-        return createScopedStyleSheets({
-          css: generateCssVarsByColorScheme(),
+        return getScopedStyleSheets(
+          generateCssVarsByColorScheme,
+          undefined,
           colorSchemeSelector,
-          prefix: cssVarPrefix,
-          name: scopeName,
-        });
+          cssVarPrefix,
+          scopeName,
+        );
       }
       return null;
     }, [

From 0b19a823043b12ee5129bb0cd5b443cdb4ac9a5e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Mon, 26 Oct 2026 15:18:06 +0100
Subject: [PATCH 06/20] [test] Add ThemeProvider benchmark

Measures mounting a root provider, and 100 nested providers whose CSS variables are the same as or differ from the outer theme's.
---
 .../src/themeProvider/themeProvider.bench.tsx | 53 +++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 test/benchmark/src/themeProvider/themeProvider.bench.tsx

diff --git a/test/benchmark/src/themeProvider/themeProvider.bench.tsx b/test/benchmark/src/themeProvider/themeProvider.bench.tsx
new file mode 100644
index 00000000000000..511c1e2cbb2997
--- /dev/null
+++ b/test/benchmark/src/themeProvider/themeProvider.bench.tsx
@@ -0,0 +1,53 @@
+import * as React from 'react';
+import { reactBenchmark } from '@mui/internal-benchmark/page';
+import Button from '@mui/material/Button';
+import { createTheme, ThemeProvider } from '@mui/material/styles';
+
+const appTheme = createTheme({ cssVariables: true, colorSchemes: { light: true, dark: true } });
+// Only changes component defaults, so its CSS variables are the same as the app theme's.
+const sameVarsTheme = createTheme({
+  cssVariables: true,
+  colorSchemes: { light: true, dark: true },
+  components: { MuiButton: { defaultProps: { disableElevation: true } } },
+});
+const promoTheme = createTheme({
+  cssVariables: true,
+  colorSchemes: {
+    light: { palette: { primary: { main: '#9c27b0' } } },
+    dark: { palette: { primary: { main: '#ce93d8' } } },
+  },
+});
+
+function Buttons({ count }: { count: number }) {
+  return Array.from({ length: count }, (_, index) => (
+    <Button key={index} variant="contained">
+      Button {index}
+    </Button>
+  ));
+}
+
+function Sections({ theme, count }: { theme: typeof appTheme; count: number }) {
+  return Array.from({ length: count }, (_, index) => (
+    <ThemeProvider key={index} theme={theme}>
+      <Buttons count={5} />
+    </ThemeProvider>
+  ));
+}
+
+reactBenchmark('ThemeProvider root mount', () => (
+  <ThemeProvider theme={appTheme}>
+    <Buttons count={500} />
+  </ThemeProvider>
+));
+
+reactBenchmark('ThemeProvider nested, same variables', () => (
+  <ThemeProvider theme={appTheme}>
+    <Sections theme={sameVarsTheme} count={100} />
+  </ThemeProvider>
+));
+
+reactBenchmark('ThemeProvider nested, different variables', () => (
+  <ThemeProvider theme={appTheme}>
+    <Sections theme={promoTheme} count={100} />
+  </ThemeProvider>
+));

From 1451e779d3341f3550c50340d018e8a28fbc1e5f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Mon, 26 Oct 2026 15:25:28 +0100
Subject: [PATCH 07/20] [docs] Treat CSS theme variables as the default in the
 nested theme note

---
 docs/data/material/customization/theming/theming.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/data/material/customization/theming/theming.md b/docs/data/material/customization/theming/theming.md
index d15068a075f890..b8bfa4b8564b88 100644
--- a/docs/data/material/customization/theming/theming.md
+++ b/docs/data/material/customization/theming/theming.md
@@ -125,7 +125,7 @@ You can extend the outer theme by providing a function:
 
 {{"component": "file://./demos/theme-nesting-extend/index.ts"}}
 
-With CSS theme variables, a nested theme whose variables differ from the outer theme sets them on an element that wraps its children.
+A nested theme whose CSS theme variables differ from the outer theme sets them on an element that wraps its children.
 See [Nested and multiple theme providers](/material-ui/customization/css-theme-variables/configuration/#nested-and-multiple-theme-providers) for details.
 
 ## CSS theme variables

From 259accef9aefd6401bc86b63373ec618ae3951a8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Mon, 26 Oct 2026 15:37:28 +0100
Subject: [PATCH 08/20] Revert "[docs] Treat CSS theme variables as the default
 in the nested theme note"

This reverts commit 1451e779d3341f3550c50340d018e8a28fbc1e5f.
---
 docs/data/material/customization/theming/theming.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/data/material/customization/theming/theming.md b/docs/data/material/customization/theming/theming.md
index b8bfa4b8564b88..d15068a075f890 100644
--- a/docs/data/material/customization/theming/theming.md
+++ b/docs/data/material/customization/theming/theming.md
@@ -125,7 +125,7 @@ You can extend the outer theme by providing a function:
 
 {{"component": "file://./demos/theme-nesting-extend/index.ts"}}
 
-A nested theme whose CSS theme variables differ from the outer theme sets them on an element that wraps its children.
+With CSS theme variables, a nested theme whose variables differ from the outer theme sets them on an element that wraps its children.
 See [Nested and multiple theme providers](/material-ui/customization/css-theme-variables/configuration/#nested-and-multiple-theme-providers) for details.
 
 ## CSS theme variables

From 475d2db565621eada66af61a29cfc5fe5b4134d1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Tue, 27 Oct 2026 13:10:07 +0100
Subject: [PATCH 09/20] [system][docs] Address review of scoped ThemeProviders

- An unnamed `scoped` provider no longer stores its mode, so it doesn't overwrite the mode of the page's provider. Named ones keep their suffixed storage keys.
- Replace characters that aren't valid in a class in the `scoped` name.
- Memoize the color scheme props instead of round-tripping them through JSON.
- Keep master's `shouldGenerateStyleSheet` block and `upperTheme` declaration.
- Document the wrapper's cost and the remount, that function themes aren't scoped, and add the v10 upgrade guide entry.
- Clean up the color scheme class in `afterEach`.
---
 .../css-theme-variables/configuration.md      | 24 +++++++----
 .../material/customization/theming/theming.md |  1 +
 .../upgrade-to-v10/upgrade-to-v10.md          | 29 ++++++++++++++
 .../src/styles/ThemeProviderScoped.test.tsx   | 21 +++++++++-
 .../src/cssVars/createCssVarsProvider.tsx     | 40 +++++++++++++------
 .../src/cssVars/scopeCssVars.test.ts          | 10 +++++
 .../mui-system/src/cssVars/scopeCssVars.ts    |  4 +-
 7 files changed, 105 insertions(+), 24 deletions(-)

diff --git a/docs/data/material/customization/css-theme-variables/configuration.md b/docs/data/material/customization/css-theme-variables/configuration.md
index 69cace591304b6..aa954066a74849 100644
--- a/docs/data/material/customization/css-theme-variables/configuration.md
+++ b/docs/data/material/customization/css-theme-variables/configuration.md
@@ -307,6 +307,10 @@ The class only sets the variables that differ, and it follows the outer light or
 
 A nested provider with the same variables, for example one that only changes `components` defaults, renders no element.
 
+The wrapper is an extra element, so `> *` and `~` selectors, and the spacing of a `Stack`, don't reach through it.
+Since it only renders when the variables differ, switching a nested provider between a theme with the same variables and one with different variables also remounts its children.
+The `component` prop below avoids both: it always renders the element you choose.
+
 Dialogs, menus, popovers, tooltips, and other components that render in a portal apply the class to their own root, so they use the nested theme too.
 For elements that other libraries portal, use the `useThemeScope()` hook to get the class:
 
@@ -319,7 +323,8 @@ function Toast() {
 }
 ```
 
-To put the class on your own element instead of the `div`, for example inside a table or a list, where a `div` isn't valid HTML, use the `component` prop:
+To put the class on your own element instead of the `div`, for example inside a table or a list, where a `div` isn't valid HTML, use the `component` prop.
+It renders whether the variables differ or not:
 
 ```jsx
 <ThemeProvider theme={promoTheme} component="tbody" className="promo">
@@ -333,16 +338,19 @@ Two `ThemeProvider`s that aren't nested in each other both write to `:root` and
 Add the `scoped` prop to the one that should only apply to its children, like an embedded widget:
 
 ```jsx
-<ThemeProvider theme={appTheme}>
-  <App />
-</ThemeProvider>
-<ThemeProvider theme={widgetTheme} scoped="widget">
-  <Widget />
-</ThemeProvider>
+<React.Fragment>
+  <ThemeProvider theme={appTheme}>
+    <App />
+  </ThemeProvider>
+  <ThemeProvider theme={widgetTheme} scoped="widget">
+    <Widget />
+  </ThemeProvider>
+</React.Fragment>
 ```
 
 A scoped provider writes all of its variables on its element, and has its own light or dark mode.
-When `scoped` is a string, it's added to the class name and to the storage keys of the mode and color scheme, for example `mui-mode-widget`.
+To remember that mode across visits, give it a name: when `scoped` is a string, it's added to the class name and to the storage keys of the mode and color scheme, for example `mui-mode-widget`.
+Without a name, the mode isn't stored, so it doesn't overwrite the mode of the page's provider.
 
 :::info
 A CSS variable that you override on `:root` doesn't reach the elements under a scoped provider that sets it, because the closest declaration wins.
diff --git a/docs/data/material/customization/theming/theming.md b/docs/data/material/customization/theming/theming.md
index d15068a075f890..d0cfc4f7dd9bb6 100644
--- a/docs/data/material/customization/theming/theming.md
+++ b/docs/data/material/customization/theming/theming.md
@@ -126,6 +126,7 @@ You can extend the outer theme by providing a function:
 {{"component": "file://./demos/theme-nesting-extend/index.ts"}}
 
 With CSS theme variables, a nested theme whose variables differ from the outer theme sets them on an element that wraps its children.
+This doesn't apply to a theme passed as a function, which still uses the outer theme's CSS variables.
 See [Nested and multiple theme providers](/material-ui/customization/css-theme-variables/configuration/#nested-and-multiple-theme-providers) for details.
 
 ## CSS theme variables
diff --git a/docs/data/material/migration/upgrade-to-v10/upgrade-to-v10.md b/docs/data/material/migration/upgrade-to-v10/upgrade-to-v10.md
index 16c5b27fa3c6d8..d3957e2c066ed2 100644
--- a/docs/data/material/migration/upgrade-to-v10/upgrade-to-v10.md
+++ b/docs/data/material/migration/upgrade-to-v10/upgrade-to-v10.md
@@ -1,3 +1,32 @@
 # Upgrade to v10
 
 <p class="description">This guide explains how to upgrade from Material UI v9 to v10.</p>
+
+## Breaking changes
+
+### Theme
+
+#### Nested ThemeProviders with CSS theme variables
+
+A nested `ThemeProvider` whose theme uses CSS theme variables now applies its theme.
+Previously, its variables were ignored when it had the same `cssVarPrefix` as the outer theme, so its subtree kept the outer theme's colors.
+
+When its variables differ from the outer theme, it wraps its children in a `div` with `display: contents` that sets them.
+Selectors like `> *` and `~`, the spacing of a `Stack`, and DOM snapshots can be affected.
+To render your own element instead, for example a `tbody` inside a table, use the `component` prop:
+
+```jsx
+<ThemeProvider theme={promoTheme} component="tbody">
+  {rows}
+</ThemeProvider>
+```
+
+Two `ThemeProvider`s that aren't nested in each other still overwrite each other's variables on `:root`, and now log a warning in development.
+Add the `scoped` prop to the one that should only apply to its children:
+
+```diff
+-<ThemeProvider theme={widgetTheme}>
++<ThemeProvider theme={widgetTheme} scoped="widget">
+```
+
+See [Nested and multiple theme providers](/material-ui/customization/css-theme-variables/configuration/#nested-and-multiple-theme-providers) for details.
diff --git a/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx b/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
index 3ea187353b48f7..4819b8c8c9b4e2 100644
--- a/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
+++ b/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
@@ -1,4 +1,4 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, afterEach } from 'vitest';
 import * as React from 'react';
 import { createRenderer, screen, isJsdom } from '@mui/internal-test-utils';
 import Button from '@mui/material/Button';
@@ -16,6 +16,10 @@ const redTheme = createTheme({ cssVariables: true, palette: { primary: { main: '
 describe('ThemeProvider with scoped CSS theme variables', () => {
   const { render } = createRenderer();
 
+  afterEach(() => {
+    document.documentElement.classList.remove('light', 'dark');
+  });
+
   describe('nested', () => {
     it('wraps the children in a scoped element when the variables differ', () => {
       render(
@@ -135,7 +139,6 @@ describe('ThemeProvider with scoped CSS theme variables', () => {
       );
       expect(document.documentElement.classList.contains('dark')).to.equal(true);
       expect(getVar(screen.getByTestId('inner'), '--mui-palette-primary-main')).to.equal('#00ff00');
-      document.documentElement.classList.remove('dark');
     });
   });
 
@@ -164,6 +167,20 @@ describe('ThemeProvider with scoped CSS theme variables', () => {
       expect(getComputedStyle(screen.getByTestId('widget')).colorScheme).to.equal('dark');
     });
 
+    it('does not store the mode of an unnamed scoped provider', () => {
+      const theme = createTheme({
+        cssVariables: { colorSchemeSelector: 'class' },
+        colorSchemes: { light: true, dark: true },
+      });
+      window.localStorage.removeItem('mui-mode');
+      render(
+        <ThemeProvider theme={theme} scoped defaultMode="dark">
+          <div />
+        </ThemeProvider>,
+      );
+      expect(window.localStorage.getItem('mui-mode')).to.equal(null);
+    });
+
     it('uses the name in the class name', () => {
       render(
         <ThemeProvider theme={redTheme} scoped="widget">
diff --git a/packages/mui-system/src/cssVars/createCssVarsProvider.tsx b/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
index 81e8b5de5d5341..fef85cd1066eb0 100644
--- a/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
+++ b/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
@@ -302,7 +302,7 @@ export default function createCssVarsProvider<
       noSsr,
     } = props;
     const hasMounted = React.useRef(false);
-    const upperTheme = muiUseTheme() as any;
+    const upperTheme = muiUseTheme();
     const ctx = React.useContext(ColorSchemeContext);
     const upperScope = React.useContext(ThemeScopeContext);
     const nested = !!ctx && !disableNestedContext;
@@ -361,7 +361,9 @@ export default function createCssVarsProvider<
       modeStorageKey,
       colorSchemeStorageKey,
       defaultMode,
-      storageManager,
+      // An unnamed scoped provider would share the storage keys of the page's provider, so it doesn't store its mode.
+      storageManager:
+        isScopedRoot && !scopeName && props.storageManager === undefined ? null : storageManager,
       storageWindow,
       noSsr,
     });
@@ -546,14 +548,14 @@ export default function createCssVarsProvider<
 
     const canGenerateStyleSheet =
       !disableStyleSheetGeneration && restThemeProp.cssVariables !== false;
-    const samePrefixAsUpper = nested && upperTheme?.cssVarPrefix === cssVarPrefix;
+    const samePrefixAsUpper = nested && (upperTheme as any)?.cssVarPrefix === cssVarPrefix;
 
     // 6. Scope the CSS theme variables that can't go to `:root` to the provider's element.
     const generateCssVarsByColorScheme: (() => CssVarsByColorScheme) | undefined =
       restThemeProp.generateCssVarsByColorScheme;
     const upperGenerateCssVarsByColorScheme: (() => CssVarsByColorScheme) | undefined =
-      samePrefixAsUpper ? upperTheme.generateCssVarsByColorScheme : undefined;
-    const upperColorSchemeSelector = nested ? upperTheme?.colorSchemeSelector : undefined;
+      samePrefixAsUpper ? (upperTheme as any).generateCssVarsByColorScheme : undefined;
+    const upperColorSchemeSelector = nested ? (upperTheme as any)?.colorSchemeSelector : undefined;
     const scope = React.useMemo(() => {
       if (!canGenerateStyleSheet || !generateCssVarsByColorScheme) {
         return null;
@@ -595,10 +597,14 @@ export default function createCssVarsProvider<
     ]);
 
     const scopeClassName = scope?.className;
-    const { className: colorSchemeClassName, ...colorSchemeAttributes } = isScopedRoot
-      ? getColorSchemeProps(colorSchemeSelector, colorScheme)
-      : ({} as Record<string, string>);
-    const colorSchemeAttributesKey = JSON.stringify(colorSchemeAttributes);
+    const colorSchemeProps = React.useMemo(
+      () =>
+        isScopedRoot
+          ? getColorSchemeProps(colorSchemeSelector, colorScheme)
+          : ({} as Record<string, string>),
+      [isScopedRoot, colorSchemeSelector, colorScheme],
+    );
+    const { className: colorSchemeClassName, ...colorSchemeAttributes } = colorSchemeProps;
     const scopeProps = React.useMemo(() => {
       if (!scopeClassName) {
         return undefined;
@@ -606,12 +612,20 @@ export default function createCssVarsProvider<
       // Portaled elements aren't under the outer scopes' elements either, so they get them too.
       return {
         ...(nested ? upperScope : undefined),
-        ...JSON.parse(colorSchemeAttributesKey),
+        ...colorSchemeProps,
         className: clsx(nested && upperScope?.className, scopeClassName, colorSchemeClassName),
       };
-    }, [scopeClassName, colorSchemeClassName, colorSchemeAttributesKey, nested, upperScope]);
-
-    const shouldGenerateStyleSheet = canGenerateStyleSheet && !samePrefixAsUpper && !isScopedRoot;
+    }, [scopeClassName, colorSchemeClassName, colorSchemeProps, nested, upperScope]);
+
+    let shouldGenerateStyleSheet = true;
+    if (
+      disableStyleSheetGeneration ||
+      restThemeProp.cssVariables === false ||
+      (nested && (upperTheme as any)?.cssVarPrefix === cssVarPrefix) ||
+      isScopedRoot
+    ) {
+      shouldGenerateStyleSheet = false;
+    }
 
     if (process.env.NODE_ENV !== 'production') {
       // eslint-disable-next-line react-hooks/rules-of-hooks
diff --git a/packages/mui-system/src/cssVars/scopeCssVars.test.ts b/packages/mui-system/src/cssVars/scopeCssVars.test.ts
index bf893b6b6368fb..c7b9e87165c224 100644
--- a/packages/mui-system/src/cssVars/scopeCssVars.test.ts
+++ b/packages/mui-system/src/cssVars/scopeCssVars.test.ts
@@ -96,6 +96,16 @@ describe('createScopedStyleSheets', () => {
     });
   });
 
+  it('replaces the characters of the name that are not valid in a class', () => {
+    const result = createScopedStyleSheets({
+      css: upper,
+      colorSchemeSelector: 'class',
+      prefix: 'mui',
+      name: 'my widget.v2',
+    })!;
+    expect(result.className).to.match(/^mui-theme-my-widget-v2-[a-z0-9]+$/);
+  });
+
   it('gives the same class name to the same declarations', () => {
     const options = { css: upper, colorSchemeSelector: 'class', prefix: 'mui' };
     expect(createScopedStyleSheets(options)!.className).to.equal(
diff --git a/packages/mui-system/src/cssVars/scopeCssVars.ts b/packages/mui-system/src/cssVars/scopeCssVars.ts
index 9d15c0dac1b128..99438563dc3043 100644
--- a/packages/mui-system/src/cssVars/scopeCssVars.ts
+++ b/packages/mui-system/src/cssVars/scopeCssVars.ts
@@ -124,7 +124,9 @@ export function createScopedStyleSheets(options: {
     return null;
   }
 
-  const className = `${prefix ? `${prefix}-` : ''}theme-${name ? `${name}-` : ''}${hash(
+  // The name is only there to make the class readable, so characters that aren't valid in a class are replaced.
+  const safeName = name?.replace(/[^a-zA-Z0-9_-]/g, '-');
+  const className = `${prefix ? `${prefix}-` : ''}theme-${safeName ? `${safeName}-` : ''}${hash(
     JSON.stringify([root, schemes, rule, !!upper]),
   )}`;
   const scope = `.${className}`;

From 43cd1819578180094d2f223c0b75f973fa5ebd39 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Tue, 27 Oct 2026 16:22:05 +0100
Subject: [PATCH 10/20] [system][docs] Set the scoped CSS theme variables on
 the provider's single child

The provider no longer renders a `display: contents` wrapper. When it needs to scope, it adds the class (and a scoped root's color scheme attribute) to its single child, so it never adds DOM and switching themes doesn't remount the children. Other children log an error in development. The `component` and `className` props are removed.
---
 .../css-theme-variables/configuration.md      |  39 +++---
 .../material/customization/theming/theming.md |   2 +-
 .../upgrade-to-v10/upgrade-to-v10.md          |  28 ++--
 .../mui-material/src/styles/ThemeProvider.tsx |  11 +-
 .../src/styles/ThemeProviderScoped.test.tsx   | 121 ++++++++++++++----
 .../src/cssVars/createCssVarsProvider.tsx     |  80 ++++++------
 6 files changed, 164 insertions(+), 117 deletions(-)

diff --git a/docs/data/material/customization/css-theme-variables/configuration.md b/docs/data/material/customization/css-theme-variables/configuration.md
index aa954066a74849..05cef7c348f413 100644
--- a/docs/data/material/customization/css-theme-variables/configuration.md
+++ b/docs/data/material/customization/css-theme-variables/configuration.md
@@ -280,22 +280,28 @@ In the example below, all the components inside the `div` will always be dark:
 ## Nested and multiple theme providers
 
 A `ThemeProvider` writes the CSS theme variables to `:root`, so they apply to the whole page.
-A nested or `scoped` provider writes them on an element that wraps its children instead, so they only apply there.
+A nested or `scoped` provider sets them on its child element instead, so they only apply there.
 
 ### Nested providers
 
-A nested `ThemeProvider` whose variables differ from the outer theme wraps its children in a `div` with `display: contents` and a generated class.
+When a nested `ThemeProvider`'s variables differ from the outer theme, it adds a generated class to its child.
 The class only sets the variables that differ, and it follows the outer light or dark mode:
 
 ```jsx
 <ThemeProvider theme={appTheme}>
   <Button>Uses appTheme</Button>
   <ThemeProvider theme={promoTheme}>
-    <Button>Uses promoTheme</Button>
+    <section>
+      <Button>Uses promoTheme</Button>
+    </section>
   </ThemeProvider>
 </ThemeProvider>
 ```
 
+```html
+<section class="mui-theme-1x2y3z">…</section>
+```
+
 ```css
 :root {
   --mui-palette-primary-main: #1976d2;
@@ -305,11 +311,9 @@ The class only sets the variables that differ, and it follows the outer light or
 }
 ```
 
-A nested provider with the same variables, for example one that only changes `components` defaults, renders no element.
-
-The wrapper is an extra element, so `> *` and `~` selectors, and the spacing of a `Stack`, don't reach through it.
-Since it only renders when the variables differ, switching a nested provider between a theme with the same variables and one with different variables also remounts its children.
-The `component` prop below avoids both: it always renders the element you choose.
+The provider doesn't render any element of its own, so the child has to be a single element that renders the `className` it receives.
+With several children, a Fragment, or text, the variables aren't applied and an error is logged in development: wrap the children in one element, for example a `div`.
+A nested provider whose theme has the same variables, for example one that only changes `components` defaults, accepts any children.
 
 Dialogs, menus, popovers, tooltips, and other components that render in a portal apply the class to their own root, so they use the nested theme too.
 For elements that other libraries portal, use the `useThemeScope()` hook to get the class:
@@ -323,19 +327,10 @@ function Toast() {
 }
 ```
 
-To put the class on your own element instead of the `div`, for example inside a table or a list, where a `div` isn't valid HTML, use the `component` prop.
-It renders whether the variables differ or not:
-
-```jsx
-<ThemeProvider theme={promoTheme} component="tbody" className="promo">
-  {rows}
-</ThemeProvider>
-```
-
 ### Sibling providers
 
 Two `ThemeProvider`s that aren't nested in each other both write to `:root` and overwrite each other, which logs a warning in development.
-Add the `scoped` prop to the one that should only apply to its children, like an embedded widget:
+Add the `scoped` prop to the one that should only apply to its child, like an embedded widget:
 
 ```jsx
 <React.Fragment>
@@ -343,18 +338,20 @@ Add the `scoped` prop to the one that should only apply to its children, like an
     <App />
   </ThemeProvider>
   <ThemeProvider theme={widgetTheme} scoped="widget">
-    <Widget />
+    <div>
+      <Widget />
+    </div>
   </ThemeProvider>
 </React.Fragment>
 ```
 
-A scoped provider writes all of its variables on its element, and has its own light or dark mode.
+A scoped provider sets all of its variables on its child element, and has its own light or dark mode.
 To remember that mode across visits, give it a name: when `scoped` is a string, it's added to the class name and to the storage keys of the mode and color scheme, for example `mui-mode-widget`.
 Without a name, the mode isn't stored, so it doesn't overwrite the mode of the page's provider.
 
 :::info
 A CSS variable that you override on `:root` doesn't reach the elements under a scoped provider that sets it, because the closest declaration wins.
-Override it on the scoped element instead, for example with the `className` prop.
+Override it on the child element instead, for example with its own class.
 :::
 
 ## Disabling CSS color scheme
diff --git a/docs/data/material/customization/theming/theming.md b/docs/data/material/customization/theming/theming.md
index d0cfc4f7dd9bb6..35507125f64c9e 100644
--- a/docs/data/material/customization/theming/theming.md
+++ b/docs/data/material/customization/theming/theming.md
@@ -125,7 +125,7 @@ You can extend the outer theme by providing a function:
 
 {{"component": "file://./demos/theme-nesting-extend/index.ts"}}
 
-With CSS theme variables, a nested theme whose variables differ from the outer theme sets them on an element that wraps its children.
+With CSS theme variables, a nested theme whose variables differ from the outer theme sets them on its child element, so the child has to be a single element.
 This doesn't apply to a theme passed as a function, which still uses the outer theme's CSS variables.
 See [Nested and multiple theme providers](/material-ui/customization/css-theme-variables/configuration/#nested-and-multiple-theme-providers) for details.
 
diff --git a/docs/data/material/migration/upgrade-to-v10/upgrade-to-v10.md b/docs/data/material/migration/upgrade-to-v10/upgrade-to-v10.md
index d3957e2c066ed2..edd326a4209917 100644
--- a/docs/data/material/migration/upgrade-to-v10/upgrade-to-v10.md
+++ b/docs/data/material/migration/upgrade-to-v10/upgrade-to-v10.md
@@ -11,22 +11,22 @@
 A nested `ThemeProvider` whose theme uses CSS theme variables now applies its theme.
 Previously, its variables were ignored when it had the same `cssVarPrefix` as the outer theme, so its subtree kept the outer theme's colors.
 
-When its variables differ from the outer theme, it wraps its children in a `div` with `display: contents` that sets them.
-Selectors like `> *` and `~`, the spacing of a `Stack`, and DOM snapshots can be affected.
-To render your own element instead, for example a `tbody` inside a table, use the `component` prop:
-
-```jsx
-<ThemeProvider theme={promoTheme} component="tbody">
-  {rows}
-</ThemeProvider>
-```
-
-Two `ThemeProvider`s that aren't nested in each other still overwrite each other's variables on `:root`, and now log a warning in development.
-Add the `scoped` prop to the one that should only apply to its children:
+When its variables differ from the outer theme, it sets them with a class on its child, so give it a single child element:
 
 ```diff
--<ThemeProvider theme={widgetTheme}>
-+<ThemeProvider theme={widgetTheme} scoped="widget">
+ <ThemeProvider theme={promoTheme}>
+-  <CssBaseline />
+-  <Section />
++  <div>
++    <CssBaseline />
++    <Section />
++  </div>
+ </ThemeProvider>
 ```
 
+With several children, a Fragment, or a child that doesn't render its `className`, the variables aren't applied, and the first two log an error in development.
+
+Two `ThemeProvider`s that aren't nested in each other still overwrite each other's variables on `:root`, and now log a warning in development.
+Add the `scoped` prop to the one that should only apply to its child, like an embedded widget.
+
 See [Nested and multiple theme providers](/material-ui/customization/css-theme-variables/configuration/#nested-and-multiple-theme-providers) for details.
diff --git a/packages/mui-material/src/styles/ThemeProvider.tsx b/packages/mui-material/src/styles/ThemeProvider.tsx
index 7c297702ed97d1..7674d45b404d2a 100644
--- a/packages/mui-material/src/styles/ThemeProvider.tsx
+++ b/packages/mui-material/src/styles/ThemeProvider.tsx
@@ -33,7 +33,7 @@ type ThemeProviderCssVariablesProps = CssThemeVariables extends { enabled: true
        */
       forceThemeRerender?: boolean | undefined;
       /**
-       * If `true`, the CSS theme variables are set on an element that wraps the children instead of `:root`,
+       * If `true`, the CSS theme variables are set on its child element instead of `:root`,
        * so they don't affect the rest of the page. Use it for a provider that isn't nested in another one,
        * like an embedded widget. Nested providers are scoped automatically when their variables differ.
        *
@@ -41,15 +41,6 @@ type ThemeProviderCssVariablesProps = CssThemeVariables extends { enabled: true
        * @default false
        */
       scoped?: boolean | string | undefined;
-      /**
-       * The element that wraps the children of a scoped provider.
-       * By default, a `div` with `display: contents`.
-       */
-      component?: React.ElementType | undefined;
-      /**
-       * The class name of the element that wraps the children of a scoped provider.
-       */
-      className?: string | undefined;
     }
   : {};
 
diff --git a/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx b/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
index 4819b8c8c9b4e2..dc17d98287a562 100644
--- a/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
+++ b/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
@@ -1,6 +1,6 @@
 import { describe, it, expect, afterEach } from 'vitest';
 import * as React from 'react';
-import { createRenderer, screen, isJsdom } from '@mui/internal-test-utils';
+import { createRenderer, screen, isJsdom, fireEvent } from '@mui/internal-test-utils';
 import Button from '@mui/material/Button';
 import Dialog from '@mui/material/Dialog';
 import Popper from '@mui/material/Popper';
@@ -21,23 +21,78 @@ describe('ThemeProvider with scoped CSS theme variables', () => {
   });
 
   describe('nested', () => {
-    it('wraps the children in a scoped element when the variables differ', () => {
+    it('adds the scope class to the child when the variables differ', () => {
       render(
         <ThemeProvider theme={blueTheme}>
           <div data-testid="outer">
             <ThemeProvider theme={redTheme}>
-              <div data-testid="inner" />
+              <div data-testid="inner" className="inner" />
             </ThemeProvider>
           </div>
         </ThemeProvider>,
       );
-      const wrapper = screen.getByTestId('inner').parentElement!;
-      expect(wrapper).not.to.equal(screen.getByTestId('outer'));
-      expect(wrapper.className).to.match(/^mui-theme-[a-z0-9]+$/);
-      expect(wrapper.style.display).to.equal('contents');
+      const inner = screen.getByTestId('inner');
+      expect(inner.parentElement).to.equal(screen.getByTestId('outer'));
+      expect(inner.className).to.match(/^inner mui-theme-[a-z0-9]+$/);
+    });
+
+    it('keeps the state of the child when the variables start to differ', () => {
+      function Counter() {
+        const [count, setCount] = React.useState(0);
+        return (
+          <button type="button" data-testid="counter" onClick={() => setCount(count + 1)}>
+            {count}
+          </button>
+        );
+      }
+      const { setProps } = render(
+        <ThemeProvider theme={blueTheme}>
+          <ThemeProvider theme={blueTheme}>
+            <Counter />
+          </ThemeProvider>
+        </ThemeProvider>,
+      );
+      fireEvent.click(screen.getByTestId('counter'));
+      setProps({
+        children: (
+          <ThemeProvider theme={redTheme}>
+            <Counter />
+          </ThemeProvider>
+        ),
+      });
+      expect(screen.getByTestId('counter').textContent).to.equal('1');
+    });
+
+    it('logs an error and applies nothing when the children are not a single element', () => {
+      expect(() =>
+        render(
+          <ThemeProvider theme={blueTheme}>
+            <ThemeProvider theme={redTheme}>
+              <div data-testid="first" />
+              <div />
+            </ThemeProvider>
+          </ThemeProvider>,
+        ),
+      ).toErrorDev("MUI: The CSS theme variables of this ThemeProvider can't be applied");
+      expect(screen.getByTestId('first').className).to.equal('');
     });
 
-    it('renders no element when the theme is the same', () => {
+    it('logs an error when the child is a Fragment', () => {
+      expect(() =>
+        render(
+          <ThemeProvider theme={blueTheme}>
+            <ThemeProvider theme={redTheme}>
+              <React.Fragment>
+                <div />
+                <div />
+              </React.Fragment>
+            </ThemeProvider>
+          </ThemeProvider>,
+        ),
+      ).toErrorDev("MUI: The CSS theme variables of this ThemeProvider can't be applied");
+    });
+
+    it('leaves any children untouched when the theme is the same', () => {
       render(
         <ThemeProvider theme={blueTheme}>
           <div data-testid="outer">
@@ -47,10 +102,10 @@ describe('ThemeProvider with scoped CSS theme variables', () => {
           </div>
         </ThemeProvider>,
       );
-      expect(screen.getByTestId('inner').parentElement).to.equal(screen.getByTestId('outer'));
+      expect(screen.getByTestId('inner').className).to.equal('');
     });
 
-    it('renders no element when the theme only changes component defaults', () => {
+    it('leaves the child untouched when the theme only changes component defaults', () => {
       const theme = createTheme({
         cssVariables: true,
         palette: { primary: { main: '#0000ff' } },
@@ -65,7 +120,7 @@ describe('ThemeProvider with scoped CSS theme variables', () => {
           </div>
         </ThemeProvider>,
       );
-      expect(screen.getByTestId('inner').parentElement).to.equal(screen.getByTestId('outer'));
+      expect(screen.getByTestId('inner').className).to.equal('');
     });
 
     it.skipIf(isJsdom())('applies the inner variables only to the children', () => {
@@ -103,10 +158,12 @@ describe('ThemeProvider with scoped CSS theme variables', () => {
       render(
         <ThemeProvider theme={blueTheme}>
           <ThemeProvider theme={redTheme}>
-            <Dialog open>
-              <div data-testid="dialog-content" />
-            </Dialog>
-            <Anchored />
+            <div>
+              <Dialog open>
+                <div data-testid="dialog-content" />
+              </Dialog>
+              <Anchored />
+            </div>
           </ThemeProvider>
         </ThemeProvider>,
       );
@@ -187,9 +244,21 @@ describe('ThemeProvider with scoped CSS theme variables', () => {
           <div data-testid="widget" />
         </ThemeProvider>,
       );
-      expect(screen.getByTestId('widget').parentElement!.className).to.match(
-        /^mui-theme-widget-[a-z0-9]+$/,
+      expect(screen.getByTestId('widget').className).to.match(/^mui-theme-widget-[a-z0-9]+$/);
+    });
+
+    it('adds the color scheme attribute to the child', () => {
+      const theme = createTheme({
+        cssVariables: { colorSchemeSelector: 'data' },
+        colorSchemes: { light: true, dark: true },
+      });
+      render(
+        <ThemeProvider theme={theme} scoped defaultMode="dark">
+          <div data-testid="widget" />
+        </ThemeProvider>,
       );
+      expect(screen.getByTestId('widget')).to.have.attribute('data-dark', '');
+      expect(document.documentElement).not.to.have.attribute('data-dark');
     });
 
     it('warns when two providers with different themes write to :root', () => {
@@ -208,18 +277,14 @@ describe('ThemeProvider with scoped CSS theme variables', () => {
     });
   });
 
-  it('renders the `component` with the scope class', () => {
+  it('leaves the children of the top-level provider untouched', () => {
     render(
-      <ThemeProvider theme={blueTheme}>
-        <ThemeProvider theme={redTheme} component="section" className="promo">
-          <div data-testid="inner" />
-        </ThemeProvider>
+      <ThemeProvider theme={redTheme}>
+        <div data-testid="first" />
+        <div />
       </ThemeProvider>,
     );
-    const section = screen.getByTestId('inner').parentElement!;
-    expect(section.tagName).to.equal('SECTION');
-    expect(section.className).to.match(/^mui-theme-[a-z0-9]+ promo$/);
-    expect(section.style.display).to.equal('');
+    expect(screen.getByTestId('first').className).to.equal('');
   });
 
   it('exposes the scope class to elements that are portaled by other libraries', () => {
@@ -230,7 +295,9 @@ describe('ThemeProvider with scoped CSS theme variables', () => {
     render(
       <ThemeProvider theme={blueTheme}>
         <ThemeProvider theme={redTheme}>
-          <Scope />
+          <div>
+            <Scope />
+          </div>
         </ThemeProvider>
       </ThemeProvider>,
     );
diff --git a/packages/mui-system/src/cssVars/createCssVarsProvider.tsx b/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
index fef85cd1066eb0..6201c43f7542ad 100644
--- a/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
+++ b/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
@@ -120,7 +120,7 @@ export interface CreateCssVarsProviderResult<
          */
         disableStyleSheetGeneration?: boolean | undefined;
         /**
-         * If `true`, the CSS theme variables are set on an element that wraps the children instead of `:root`,
+         * If `true`, the CSS theme variables are set on its child element instead of `:root`,
          * so they don't affect the rest of the page. Use it for a provider that isn't nested in another one,
          * like an embedded widget. Nested providers are scoped automatically when their variables differ.
          *
@@ -128,15 +128,6 @@ export interface CreateCssVarsProviderResult<
          * @default false
          */
         scoped?: boolean | string | undefined;
-        /**
-         * The element that wraps the children of a scoped provider.
-         * By default, a `div` with `display: contents`.
-         */
-        component?: React.ElementType | undefined;
-        /**
-         * The class name of the element that wraps the children of a scoped provider.
-         */
-        className?: string | undefined;
       }
     >,
   ) => React.JSX.Element;
@@ -236,7 +227,6 @@ export default function createCssVarsProvider<
 
   const defaultColorSchemes = {};
   const defaultComponents = {};
-  const scopeStyle = { display: 'contents' };
 
   // The scoped stylesheets only depend on the themes, so they're created once per pair of themes
   // instead of once per provider.
@@ -288,8 +278,6 @@ export default function createCssVarsProvider<
       children,
       theme: themeProp,
       scoped = false,
-      component,
-      className,
       disableTransitionOnChange = designSystemTransitionOnChange,
       storageManager,
       storageWindow = typeof window === 'undefined' ? undefined : window,
@@ -657,37 +645,49 @@ export default function createCssVarsProvider<
       }, [shouldGenerateStyleSheet, nested, memoTheme, cssVarPrefix]);
     }
 
-    let element = (
+    // The scope class goes on the single child, so the provider never renders an element of its own.
+    const canCloneChild = React.isValidElement(children) && children.type !== React.Fragment;
+    let scopedChildren = children;
+    if (scopeClassName && canCloneChild) {
+      const child = children as React.ReactElement<{ className?: string | undefined }>;
+      scopedChildren = React.cloneElement(child, {
+        ...colorSchemeAttributes,
+        className: clsx(child.props.className, scopeClassName, colorSchemeClassName),
+      });
+    }
+
+    if (process.env.NODE_ENV !== 'production') {
+      // eslint-disable-next-line react-hooks/rules-of-hooks
+      const warnedChildren = React.useRef(false);
+      // eslint-disable-next-line react-hooks/rules-of-hooks
+      React.useEffect(() => {
+        if (scopeClassName && !canCloneChild && !warnedChildren.current) {
+          warnedChildren.current = true;
+          console.error(
+            [
+              "MUI: The CSS theme variables of this ThemeProvider can't be applied because its children aren't a single element.",
+              'Wrap its children in one element, for example a `div`, so it can set them on it.',
+            ].join('\n'),
+          );
+        }
+      }, [scopeClassName, canCloneChild]);
+    }
+
+    // The tree is the same whether the theme needs a scope or not, so switching themes keeps the children's state.
+    const element = (
       <React.Fragment>
         <ThemeProvider themeId={scopedTheme ? themeId : undefined} theme={memoTheme}>
-          {children}
+          <ThemeScopeContext.Provider value={scopeProps ?? (nested ? upperScope : undefined)}>
+            {scopedChildren}
+          </ThemeScopeContext.Provider>
         </ThemeProvider>
         {shouldGenerateStyleSheet && (
           <GlobalStyles styles={memoTheme.generateStyleSheets?.() || []} />
         )}
+        {scope && <GlobalStyles styles={scope.styles} />}
       </React.Fragment>
     );
 
-    if (scope || component) {
-      const ScopeComponent = component || 'div';
-      element = (
-        <React.Fragment>
-          {scope && <GlobalStyles styles={scope.styles} />}
-          <ScopeComponent
-            {...colorSchemeAttributes}
-            className={clsx(scopeClassName, colorSchemeClassName, className) || undefined}
-            style={component ? undefined : scopeStyle}
-          >
-            {scopeProps ? (
-              <ThemeScopeContext.Provider value={scopeProps}>{element}</ThemeScopeContext.Provider>
-            ) : (
-              element
-            )}
-          </ScopeComponent>
-        </React.Fragment>
-      );
-    }
-
     if (nested) {
       return element;
     }
@@ -702,10 +702,6 @@ export default function createCssVarsProvider<
      * The component tree.
      */
     children: PropTypes.node,
-    /**
-     * The class name of the element that wraps the children of a scoped provider.
-     */
-    className: PropTypes.string,
     /**
      * The node used to attach the color-scheme attribute
      */
@@ -714,10 +710,6 @@ export default function createCssVarsProvider<
      * localStorage key used to store `colorScheme`
      */
     colorSchemeStorageKey: PropTypes.string,
-    /**
-     * The element that wraps the children of a scoped provider.
-     */
-    component: PropTypes.elementType,
     /**
      * The default mode when the storage is empty,
      * require the theme to have `colorSchemes` with light and dark.
@@ -755,7 +747,7 @@ export default function createCssVarsProvider<
      */
     noSsr: PropTypes.bool,
     /**
-     * If `true`, the CSS theme variables are set on an element that wraps the children instead of `:root`.
+     * If `true`, the CSS theme variables are set on its child element instead of `:root`.
      */
     scoped: PropTypes.oneOfType([PropTypes.bool, PropTypes.string]),
     /**

From f11a7da538a0f9924243c2b788f9aaf7985a9a05 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Tue, 27 Oct 2026 16:23:00 +0100
Subject: [PATCH 11/20] [test] Remove the ThemeProvider benchmark

It's kept out of this pull request, matching how the other benchmark files were added. The results are in the description.
---
 .../src/themeProvider/themeProvider.bench.tsx | 53 -------------------
 1 file changed, 53 deletions(-)
 delete mode 100644 test/benchmark/src/themeProvider/themeProvider.bench.tsx

diff --git a/test/benchmark/src/themeProvider/themeProvider.bench.tsx b/test/benchmark/src/themeProvider/themeProvider.bench.tsx
deleted file mode 100644
index 511c1e2cbb2997..00000000000000
--- a/test/benchmark/src/themeProvider/themeProvider.bench.tsx
+++ /dev/null
@@ -1,53 +0,0 @@
-import * as React from 'react';
-import { reactBenchmark } from '@mui/internal-benchmark/page';
-import Button from '@mui/material/Button';
-import { createTheme, ThemeProvider } from '@mui/material/styles';
-
-const appTheme = createTheme({ cssVariables: true, colorSchemes: { light: true, dark: true } });
-// Only changes component defaults, so its CSS variables are the same as the app theme's.
-const sameVarsTheme = createTheme({
-  cssVariables: true,
-  colorSchemes: { light: true, dark: true },
-  components: { MuiButton: { defaultProps: { disableElevation: true } } },
-});
-const promoTheme = createTheme({
-  cssVariables: true,
-  colorSchemes: {
-    light: { palette: { primary: { main: '#9c27b0' } } },
-    dark: { palette: { primary: { main: '#ce93d8' } } },
-  },
-});
-
-function Buttons({ count }: { count: number }) {
-  return Array.from({ length: count }, (_, index) => (
-    <Button key={index} variant="contained">
-      Button {index}
-    </Button>
-  ));
-}
-
-function Sections({ theme, count }: { theme: typeof appTheme; count: number }) {
-  return Array.from({ length: count }, (_, index) => (
-    <ThemeProvider key={index} theme={theme}>
-      <Buttons count={5} />
-    </ThemeProvider>
-  ));
-}
-
-reactBenchmark('ThemeProvider root mount', () => (
-  <ThemeProvider theme={appTheme}>
-    <Buttons count={500} />
-  </ThemeProvider>
-));
-
-reactBenchmark('ThemeProvider nested, same variables', () => (
-  <ThemeProvider theme={appTheme}>
-    <Sections theme={sameVarsTheme} count={100} />
-  </ThemeProvider>
-));
-
-reactBenchmark('ThemeProvider nested, different variables', () => (
-  <ThemeProvider theme={appTheme}>
-    <Sections theme={promoTheme} count={100} />
-  </ThemeProvider>
-));

From ea5ad042550e45ed6d778dff0f05a17a25d9d769 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Tue, 27 Oct 2026 17:02:03 +0100
Subject: [PATCH 12/20] [test] Use a fake storage window in the scoped provider
 storage test

CI mocks window.localStorage without removeItem, so the test now checks which keys the providers read from a storage window it controls.
---
 .../src/styles/ThemeProviderScoped.test.tsx   | 31 +++++++++++++++----
 1 file changed, 25 insertions(+), 6 deletions(-)

diff --git a/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx b/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
index dc17d98287a562..e3fdb606dbcac8 100644
--- a/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
+++ b/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
@@ -224,18 +224,37 @@ describe('ThemeProvider with scoped CSS theme variables', () => {
       expect(getComputedStyle(screen.getByTestId('widget')).colorScheme).to.equal('dark');
     });
 
-    it('does not store the mode of an unnamed scoped provider', () => {
+    it('only uses the storage for a named scoped provider', () => {
       const theme = createTheme({
         cssVariables: { colorSchemeSelector: 'class' },
         colorSchemes: { light: true, dark: true },
       });
-      window.localStorage.removeItem('mui-mode');
+      const readKeys: string[] = [];
+      const storageWindow = {
+        localStorage: {
+          getItem: (key: string) => {
+            readKeys.push(key);
+            return null;
+          },
+          setItem: () => {},
+        },
+        addEventListener: () => {},
+        removeEventListener: () => {},
+      } as unknown as Window;
       render(
-        <ThemeProvider theme={theme} scoped defaultMode="dark">
-          <div />
-        </ThemeProvider>,
+        <React.Fragment>
+          <ThemeProvider theme={theme} scoped storageWindow={storageWindow}>
+            <div />
+          </ThemeProvider>
+          <ThemeProvider theme={theme} scoped="widget" storageWindow={storageWindow}>
+            <div />
+          </ThemeProvider>
+        </React.Fragment>,
+      );
+      expect(readKeys.length).to.be.greaterThan(0);
+      expect(readKeys.every((key) => key.endsWith('-widget') || key.includes('-widget-'))).to.equal(
+        true,
       );
-      expect(window.localStorage.getItem('mui-mode')).to.equal(null);
     });
 
     it('uses the name in the class name', () => {

From 618ec3fccaaddb40d8969cae2fceef2a24f74003 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Tue, 27 Oct 2026 22:36:57 +0100
Subject: [PATCH 13/20] [system][docs] Pass the scope through directly nested
 ThemeProviders

- A provider whose child is another ThemeProvider lost its scope, because the inner provider ignored the class it received. Providers, including ones with a function or non-CSS variables theme, now pass that class and the color scheme attributes on to their own child.
- Don't log the single-child error when there are no children.
- Docs: show a custom component that forwards `className`, mention `data-*` for a scoped provider with a data attribute selector, and don't use CssBaseline in the migration example.
- Update comments and the `scoped` JSDoc for the single-child requirement.
---
 .../css-theme-variables/configuration.md      |  9 ++++
 .../upgrade-to-v10/upgrade-to-v10.md          |  4 +-
 .../mui-material/src/styles/ThemeProvider.tsx | 23 +++++++++-
 .../src/styles/ThemeProviderScoped.test.tsx   | 42 +++++++++++++++++++
 .../src/cssVars/createCssVarsProvider.tsx     | 31 +++++++++++---
 5 files changed, 100 insertions(+), 9 deletions(-)

diff --git a/docs/data/material/customization/css-theme-variables/configuration.md b/docs/data/material/customization/css-theme-variables/configuration.md
index 05cef7c348f413..2c17437ad44624 100644
--- a/docs/data/material/customization/css-theme-variables/configuration.md
+++ b/docs/data/material/customization/css-theme-variables/configuration.md
@@ -313,6 +313,14 @@ The class only sets the variables that differ, and it follows the outer light or
 
 The provider doesn't render any element of its own, so the child has to be a single element that renders the `className` it receives.
 With several children, a Fragment, or text, the variables aren't applied and an error is logged in development: wrap the children in one element, for example a `div`.
+If the child is your own component, pass `className` on to its root element:
+
+```jsx
+function Section({ className, children }) {
+  return <section className={className}>{children}</section>;
+}
+```
+
 A nested provider whose theme has the same variables, for example one that only changes `components` defaults, accepts any children.
 
 Dialogs, menus, popovers, tooltips, and other components that render in a portal apply the class to their own root, so they use the nested theme too.
@@ -346,6 +354,7 @@ Add the `scoped` prop to the one that should only apply to its child, like an em
 ```
 
 A scoped provider sets all of its variables on its child element, and has its own light or dark mode.
+If the theme's `colorSchemeSelector` uses a data attribute, the child also needs to render the `data-*` props it receives.
 To remember that mode across visits, give it a name: when `scoped` is a string, it's added to the class name and to the storage keys of the mode and color scheme, for example `mui-mode-widget`.
 Without a name, the mode isn't stored, so it doesn't overwrite the mode of the page's provider.
 
diff --git a/docs/data/material/migration/upgrade-to-v10/upgrade-to-v10.md b/docs/data/material/migration/upgrade-to-v10/upgrade-to-v10.md
index edd326a4209917..cfb56dff56db4c 100644
--- a/docs/data/material/migration/upgrade-to-v10/upgrade-to-v10.md
+++ b/docs/data/material/migration/upgrade-to-v10/upgrade-to-v10.md
@@ -15,10 +15,10 @@ When its variables differ from the outer theme, it sets them with a class on its
 
 ```diff
  <ThemeProvider theme={promoTheme}>
--  <CssBaseline />
+-  <Header />
 -  <Section />
 +  <div>
-+    <CssBaseline />
++    <Header />
 +    <Section />
 +  </div>
  </ThemeProvider>
diff --git a/packages/mui-material/src/styles/ThemeProvider.tsx b/packages/mui-material/src/styles/ThemeProvider.tsx
index 7674d45b404d2a..447267667a730d 100644
--- a/packages/mui-material/src/styles/ThemeProvider.tsx
+++ b/packages/mui-material/src/styles/ThemeProvider.tsx
@@ -1,5 +1,6 @@
 'use client';
 import * as React from 'react';
+import clsx from 'clsx';
 import { DefaultTheme } from '@mui/system';
 import { StorageManager } from '@mui/system/cssVars';
 import ThemeProviderNoVars from './ThemeProviderNoVars';
@@ -36,6 +37,7 @@ type ThemeProviderCssVariablesProps = CssThemeVariables extends { enabled: true
        * If `true`, the CSS theme variables are set on its child element instead of `:root`,
        * so they don't affect the rest of the page. Use it for a provider that isn't nested in another one,
        * like an embedded widget. Nested providers are scoped automatically when their variables differ.
+       * Either way, the provider needs a single child element that renders the `className` it receives.
        *
        * A string is used as a readable part of the class name, and to suffix the storage keys.
        * @default false
@@ -112,7 +114,26 @@ export default function ThemeProvider<Theme = DefaultTheme>({
   }, [theme]);
 
   if (noVarsTheme) {
-    return <ThemeProviderNoVars theme={noVarsTheme} {...props} />;
+    // It doesn't scope its own theme, but passes on the scope that an outer provider gave it to its child.
+    const forwardedClassName = (props as { className?: string | undefined }).className;
+    let { children } = props;
+    if (forwardedClassName && React.isValidElement(children) && children.type !== React.Fragment) {
+      const child = children as React.ReactElement<{ className?: string | undefined }>;
+      const forwarded: Record<string, unknown> = {
+        className: clsx(child.props.className, forwardedClassName),
+      };
+      Object.keys(props).forEach((key) => {
+        if (key.startsWith('data-')) {
+          forwarded[key] = (props as Record<string, unknown>)[key];
+        }
+      });
+      children = React.cloneElement(child, forwarded);
+    }
+    return (
+      <ThemeProviderNoVars theme={noVarsTheme} {...props}>
+        {children}
+      </ThemeProviderNoVars>
+    );
   }
   return <CssVarsProvider theme={theme as unknown as CssVarsTheme} {...props} />;
 }
diff --git a/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx b/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
index e3fdb606dbcac8..d7529d53ddd352 100644
--- a/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
+++ b/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
@@ -77,6 +77,48 @@ describe('ThemeProvider with scoped CSS theme variables', () => {
       expect(screen.getByTestId('first').className).to.equal('');
     });
 
+    it('does not log an error when there are no children', () => {
+      render(
+        <ThemeProvider theme={blueTheme}>
+          <ThemeProvider theme={redTheme}>{false}</ThemeProvider>
+          <ThemeProvider theme={redTheme}>{null}</ThemeProvider>
+        </ThemeProvider>,
+      );
+    });
+
+    it.skipIf(isJsdom())('passes the scope of a provider whose child is another provider', () => {
+      const greenSecondaryTheme = createTheme({
+        cssVariables: true,
+        palette: { primary: { main: '#ff0000' }, secondary: { main: '#00ff00' } },
+      });
+      render(
+        <ThemeProvider theme={blueTheme}>
+          <ThemeProvider theme={redTheme}>
+            <ThemeProvider theme={greenSecondaryTheme}>
+              <div data-testid="inner" />
+            </ThemeProvider>
+          </ThemeProvider>
+        </ThemeProvider>,
+      );
+      expect(getVar(screen.getByTestId('inner'), '--mui-palette-primary-main')).to.equal('#ff0000');
+      expect(getVar(screen.getByTestId('inner'), '--mui-palette-secondary-main')).to.equal(
+        '#00ff00',
+      );
+    });
+
+    it('passes the scope through a provider with a function theme', () => {
+      render(
+        <ThemeProvider theme={blueTheme}>
+          <ThemeProvider theme={redTheme}>
+            <ThemeProvider theme={(outer: object) => ({ ...outer })}>
+              <div data-testid="inner" />
+            </ThemeProvider>
+          </ThemeProvider>
+        </ThemeProvider>,
+      );
+      expect(screen.getByTestId('inner').className).to.match(/^mui-theme-[a-z0-9]+$/);
+    });
+
     it('logs an error when the child is a Fragment', () => {
       expect(() =>
         render(
diff --git a/packages/mui-system/src/cssVars/createCssVarsProvider.tsx b/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
index 6201c43f7542ad..9e89781ee0fc73 100644
--- a/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
+++ b/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
@@ -123,6 +123,7 @@ export interface CreateCssVarsProviderResult<
          * If `true`, the CSS theme variables are set on its child element instead of `:root`,
          * so they don't affect the rest of the page. Use it for a provider that isn't nested in another one,
          * like an embedded widget. Nested providers are scoped automatically when their variables differ.
+         * Either way, the provider needs a single child element that renders the `className` it receives.
          *
          * A string is used as a readable part of the class name, and to suffix the storage keys.
          * @default false
@@ -421,7 +422,7 @@ export default function createCssVarsProvider<
 
     // 5. Declaring effects
     // 5.1 Updates the selector value to use the current color scheme which tells CSS to use the proper stylesheet.
-    // A scoped root renders it on its own element instead.
+    // A scoped root sets it on its child instead.
     const colorSchemeSelector = restThemeProp.colorSchemeSelector;
     const ownsColorSchemeNode = !isScopedRoot || props.colorSchemeNode !== undefined;
     useEnhancedEffect(() => {
@@ -538,7 +539,7 @@ export default function createCssVarsProvider<
       !disableStyleSheetGeneration && restThemeProp.cssVariables !== false;
     const samePrefixAsUpper = nested && (upperTheme as any)?.cssVarPrefix === cssVarPrefix;
 
-    // 6. Scope the CSS theme variables that can't go to `:root` to the provider's element.
+    // 6. Scope the CSS theme variables that can't go to `:root` to the provider's child.
     const generateCssVarsByColorScheme: (() => CssVarsByColorScheme) | undefined =
       restThemeProp.generateCssVarsByColorScheme;
     const upperGenerateCssVarsByColorScheme: (() => CssVarsByColorScheme) | undefined =
@@ -646,13 +647,31 @@ export default function createCssVarsProvider<
     }
 
     // The scope class goes on the single child, so the provider never renders an element of its own.
+    // When the child is itself a ThemeProvider, it receives the outer scope and passes it on to its own child.
+    const forwardedClassName: string | undefined = props.className;
+    const needsChildScope = !!(scopeClassName || forwardedClassName);
+    const hasChildren = children != null && typeof children !== 'boolean';
     const canCloneChild = React.isValidElement(children) && children.type !== React.Fragment;
     let scopedChildren = children;
-    if (scopeClassName && canCloneChild) {
+    if (needsChildScope && canCloneChild) {
       const child = children as React.ReactElement<{ className?: string | undefined }>;
+      const forwardedAttributes: Record<string, string> = {};
+      if (forwardedClassName) {
+        Object.keys(props).forEach((key) => {
+          if (key.startsWith('data-')) {
+            forwardedAttributes[key] = props[key];
+          }
+        });
+      }
       scopedChildren = React.cloneElement(child, {
+        ...forwardedAttributes,
         ...colorSchemeAttributes,
-        className: clsx(child.props.className, scopeClassName, colorSchemeClassName),
+        className: clsx(
+          child.props.className,
+          forwardedClassName,
+          scopeClassName,
+          colorSchemeClassName,
+        ),
       });
     }
 
@@ -661,7 +680,7 @@ export default function createCssVarsProvider<
       const warnedChildren = React.useRef(false);
       // eslint-disable-next-line react-hooks/rules-of-hooks
       React.useEffect(() => {
-        if (scopeClassName && !canCloneChild && !warnedChildren.current) {
+        if (needsChildScope && hasChildren && !canCloneChild && !warnedChildren.current) {
           warnedChildren.current = true;
           console.error(
             [
@@ -670,7 +689,7 @@ export default function createCssVarsProvider<
             ].join('\n'),
           );
         }
-      }, [scopeClassName, canCloneChild]);
+      }, [needsChildScope, hasChildren, canCloneChild]);
     }
 
     // The tree is the same whether the theme needs a scope or not, so switching themes keeps the children's state.

From eae0c4ca4ff584ca6258117c41f0096cd8db2d2e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Tue, 27 Oct 2026 23:08:45 +0100
Subject: [PATCH 14/20] [material-ui] Don't pass the forwarded scope props to
 the system ThemeProvider

The system ThemeProvider only accepts its own props, so on React 17 and 18 the forwarded `className` and `data-*` logged a prop types error in development when the middle provider had a function or non-CSS variables theme. They're now only cloned onto the child. Adds a test for the color scheme attribute passing through a function theme.
---
 .../mui-material/src/styles/ThemeProvider.tsx | 23 +++++++++++--------
 .../src/styles/ThemeProviderScoped.test.tsx   | 16 +++++++++++++
 2 files changed, 30 insertions(+), 9 deletions(-)

diff --git a/packages/mui-material/src/styles/ThemeProvider.tsx b/packages/mui-material/src/styles/ThemeProvider.tsx
index 447267667a730d..d5414a8281e391 100644
--- a/packages/mui-material/src/styles/ThemeProvider.tsx
+++ b/packages/mui-material/src/styles/ThemeProvider.tsx
@@ -115,22 +115,27 @@ export default function ThemeProvider<Theme = DefaultTheme>({
 
   if (noVarsTheme) {
     // It doesn't scope its own theme, but passes on the scope that an outer provider gave it to its child.
-    const forwardedClassName = (props as { className?: string | undefined }).className;
+    // The system ThemeProvider only accepts its own props, so the forwarded ones don't reach it.
+    const { className: forwardedClassName, ...noVarsProps } = props as typeof props & {
+      className?: string | undefined;
+    };
+    const forwarded: Record<string, unknown> = {};
+    Object.keys(noVarsProps).forEach((key) => {
+      if (key.startsWith('data-')) {
+        forwarded[key] = (noVarsProps as Record<string, unknown>)[key];
+        delete (noVarsProps as Record<string, unknown>)[key];
+      }
+    });
     let { children } = props;
     if (forwardedClassName && React.isValidElement(children) && children.type !== React.Fragment) {
       const child = children as React.ReactElement<{ className?: string | undefined }>;
-      const forwarded: Record<string, unknown> = {
+      children = React.cloneElement(child, {
+        ...forwarded,
         className: clsx(child.props.className, forwardedClassName),
-      };
-      Object.keys(props).forEach((key) => {
-        if (key.startsWith('data-')) {
-          forwarded[key] = (props as Record<string, unknown>)[key];
-        }
       });
-      children = React.cloneElement(child, forwarded);
     }
     return (
-      <ThemeProviderNoVars theme={noVarsTheme} {...props}>
+      <ThemeProviderNoVars theme={noVarsTheme} {...noVarsProps}>
         {children}
       </ThemeProviderNoVars>
     );
diff --git a/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx b/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
index d7529d53ddd352..008818a2692c76 100644
--- a/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
+++ b/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
@@ -119,6 +119,22 @@ describe('ThemeProvider with scoped CSS theme variables', () => {
       expect(screen.getByTestId('inner').className).to.match(/^mui-theme-[a-z0-9]+$/);
     });
 
+    it('passes the color scheme attribute of a scoped provider through a function theme', () => {
+      const theme = createTheme({
+        cssVariables: { colorSchemeSelector: 'data' },
+        colorSchemes: { light: true, dark: true },
+      });
+      render(
+        <ThemeProvider theme={theme} scoped defaultMode="dark">
+          <ThemeProvider theme={(outer: object) => ({ ...outer })}>
+            <div data-testid="widget" />
+          </ThemeProvider>
+        </ThemeProvider>,
+      );
+      expect(screen.getByTestId('widget')).to.have.attribute('data-dark', '');
+      expect(screen.getByTestId('widget').className).to.match(/^mui-theme-[a-z0-9]+$/);
+    });
+
     it('logs an error when the child is a Fragment', () => {
       expect(() =>
         render(

From 6d8f9fbdea80714a3a71d8a6dc80f15f4f132475 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Tue, 27 Oct 2026 23:17:49 +0100
Subject: [PATCH 15/20] [system][material-ui] Share the scope forwarding
 between the ThemeProviders

The CSS variables provider and Material's ThemeProvider for themes without CSS variables both passed the outer scope on to their child with their own copy of the code. They now use one helper, exported from `@mui/system/cssVars` as `unstable_applyScopeToChild`.
---
 .../mui-material/src/styles/ThemeProvider.tsx | 20 +++-------
 .../src/cssVars/createCssVarsProvider.tsx     | 38 +++++++------------
 packages/mui-system/src/cssVars/index.ts      |  1 +
 .../mui-system/src/cssVars/scopeCssVars.ts    | 36 ++++++++++++++++++
 4 files changed, 56 insertions(+), 39 deletions(-)

diff --git a/packages/mui-material/src/styles/ThemeProvider.tsx b/packages/mui-material/src/styles/ThemeProvider.tsx
index d5414a8281e391..7e83f965708e51 100644
--- a/packages/mui-material/src/styles/ThemeProvider.tsx
+++ b/packages/mui-material/src/styles/ThemeProvider.tsx
@@ -1,8 +1,10 @@
 'use client';
 import * as React from 'react';
-import clsx from 'clsx';
 import { DefaultTheme } from '@mui/system';
-import { StorageManager } from '@mui/system/cssVars';
+import {
+  StorageManager,
+  unstable_applyScopeToChild as applyScopeToChild,
+} from '@mui/system/cssVars';
 import ThemeProviderNoVars from './ThemeProviderNoVars';
 import { CssThemeVariables } from './createThemeNoVars';
 import { CssVarsProvider } from './ThemeProviderWithVars';
@@ -116,27 +118,17 @@ export default function ThemeProvider<Theme = DefaultTheme>({
   if (noVarsTheme) {
     // It doesn't scope its own theme, but passes on the scope that an outer provider gave it to its child.
     // The system ThemeProvider only accepts its own props, so the forwarded ones don't reach it.
-    const { className: forwardedClassName, ...noVarsProps } = props as typeof props & {
+    const { className, ...noVarsProps } = props as typeof props & {
       className?: string | undefined;
     };
-    const forwarded: Record<string, unknown> = {};
     Object.keys(noVarsProps).forEach((key) => {
       if (key.startsWith('data-')) {
-        forwarded[key] = (noVarsProps as Record<string, unknown>)[key];
         delete (noVarsProps as Record<string, unknown>)[key];
       }
     });
-    let { children } = props;
-    if (forwardedClassName && React.isValidElement(children) && children.type !== React.Fragment) {
-      const child = children as React.ReactElement<{ className?: string | undefined }>;
-      children = React.cloneElement(child, {
-        ...forwarded,
-        className: clsx(child.props.className, forwardedClassName),
-      });
-    }
     return (
       <ThemeProviderNoVars theme={noVarsTheme} {...noVarsProps}>
-        {children}
+        {applyScopeToChild(props.children, props)}
       </ThemeProviderNoVars>
     );
   }
diff --git a/packages/mui-system/src/cssVars/createCssVarsProvider.tsx b/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
index 9e89781ee0fc73..7f1436f75417c0 100644
--- a/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
+++ b/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
@@ -16,6 +16,7 @@ import useCurrentColorScheme, { type Result } from './useCurrentColorScheme';
 import type { StorageManager } from './localStorageManager';
 import ThemeScopeContext from './ThemeScopeContext';
 import {
+  applyScopeToChild,
   createScopedStyleSheets,
   getColorSchemeProps,
   type CssVarsByColorScheme,
@@ -648,34 +649,21 @@ export default function createCssVarsProvider<
 
     // The scope class goes on the single child, so the provider never renders an element of its own.
     // When the child is itself a ThemeProvider, it receives the outer scope and passes it on to its own child.
-    const forwardedClassName: string | undefined = props.className;
-    const needsChildScope = !!(scopeClassName || forwardedClassName);
-    const hasChildren = children != null && typeof children !== 'boolean';
-    const canCloneChild = React.isValidElement(children) && children.type !== React.Fragment;
-    let scopedChildren = children;
-    if (needsChildScope && canCloneChild) {
-      const child = children as React.ReactElement<{ className?: string | undefined }>;
-      const forwardedAttributes: Record<string, string> = {};
-      if (forwardedClassName) {
-        Object.keys(props).forEach((key) => {
-          if (key.startsWith('data-')) {
-            forwardedAttributes[key] = props[key];
+    const scopedChildren = applyScopeToChild(
+      children,
+      props,
+      scopeClassName
+        ? {
+            className: clsx(scopeClassName, colorSchemeClassName),
+            attributes: colorSchemeAttributes,
           }
-        });
-      }
-      scopedChildren = React.cloneElement(child, {
-        ...forwardedAttributes,
-        ...colorSchemeAttributes,
-        className: clsx(
-          child.props.className,
-          forwardedClassName,
-          scopeClassName,
-          colorSchemeClassName,
-        ),
-      });
-    }
+        : undefined,
+    );
 
     if (process.env.NODE_ENV !== 'production') {
+      const needsChildScope = !!(scopeClassName || props.className);
+      const hasChildren = children != null && typeof children !== 'boolean';
+      const canCloneChild = React.isValidElement(children) && children.type !== React.Fragment;
       // eslint-disable-next-line react-hooks/rules-of-hooks
       const warnedChildren = React.useRef(false);
       // eslint-disable-next-line react-hooks/rules-of-hooks
diff --git a/packages/mui-system/src/cssVars/index.ts b/packages/mui-system/src/cssVars/index.ts
index 9fc9a2259ec334..de5eb7d5c8cc45 100644
--- a/packages/mui-system/src/cssVars/index.ts
+++ b/packages/mui-system/src/cssVars/index.ts
@@ -13,3 +13,4 @@ export { createGetColorSchemeSelector } from './getColorSchemeSelector';
 export type { StorageManager } from './localStorageManager';
 export { useThemeScope } from './ThemeScopeContext';
 export type { ThemeScopeProps } from './ThemeScopeContext';
+export { applyScopeToChild as unstable_applyScopeToChild } from './scopeCssVars';
diff --git a/packages/mui-system/src/cssVars/scopeCssVars.ts b/packages/mui-system/src/cssVars/scopeCssVars.ts
index 99438563dc3043..ecc4d4c172cc6d 100644
--- a/packages/mui-system/src/cssVars/scopeCssVars.ts
+++ b/packages/mui-system/src/cssVars/scopeCssVars.ts
@@ -1,3 +1,6 @@
+import * as React from 'react';
+import clsx from 'clsx';
+
 type CssDeclarations = Record<string, string | number>;
 
 export interface CssVarsByColorScheme {
@@ -163,3 +166,36 @@ export function createScopedStyleSheets(options: {
 
   return { className, styles };
 }
+
+/**
+ * Adds the scope that an outer ThemeProvider passed in `props` (`className` and `data-*`),
+ * and the provider's own scope, to its single child element.
+ * Returns the children unchanged when there's nothing to add or they aren't a single element.
+ */
+export function applyScopeToChild(
+  children: React.ReactNode,
+  props: Record<string, any>,
+  own?: { className?: string | undefined; attributes?: Record<string, string> | undefined },
+): React.ReactNode {
+  const forwardedClassName: string | undefined = props.className;
+  if (!forwardedClassName && !own?.className) {
+    return children;
+  }
+  if (!React.isValidElement(children) || children.type === React.Fragment) {
+    return children;
+  }
+  const child = children as React.ReactElement<{ className?: string | undefined }>;
+  const forwardedAttributes: Record<string, string> = {};
+  if (forwardedClassName) {
+    Object.keys(props).forEach((key) => {
+      if (key.startsWith('data-')) {
+        forwardedAttributes[key] = props[key];
+      }
+    });
+  }
+  return React.cloneElement(child, {
+    ...forwardedAttributes,
+    ...own?.attributes,
+    className: clsx(child.props.className, forwardedClassName, own?.className),
+  });
+}

From 5c5dde4083177fc5d4515869db196fe451c81dd1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Tue, 27 Oct 2026 23:27:47 +0100
Subject: [PATCH 16/20] [docs] Add a temporary ThemeProvider scoping playground

Each scenario renders in its own iframe next to an inspector of the scope classes, computed variables and generated rules. To be removed before merging.
---
 .../experiments/theme-provider-scoping.tsx    | 799 ++++++++++++++++++
 1 file changed, 799 insertions(+)
 create mode 100644 docs/pages/experiments/theme-provider-scoping.tsx

diff --git a/docs/pages/experiments/theme-provider-scoping.tsx b/docs/pages/experiments/theme-provider-scoping.tsx
new file mode 100644
index 00000000000000..951a6538d3861a
--- /dev/null
+++ b/docs/pages/experiments/theme-provider-scoping.tsx
@@ -0,0 +1,799 @@
+'use client';
+// Temporary playground for https://github.com/mui/material-ui/pull/49581. Remove before merging.
+import * as React from 'react';
+import * as ReactDOM from 'react-dom';
+import createCache, { EmotionCache } from '@emotion/cache';
+import { CacheProvider } from '@emotion/react';
+import Box from '@mui/material/Box';
+import Button from '@mui/material/Button';
+import Chip from '@mui/material/Chip';
+import Dialog from '@mui/material/Dialog';
+import DialogContent from '@mui/material/DialogContent';
+import Menu from '@mui/material/Menu';
+import MenuItem from '@mui/material/MenuItem';
+import Tooltip from '@mui/material/Tooltip';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+import {
+  ThemeProvider as MaterialThemeProvider,
+  createTheme,
+  useColorScheme,
+  useThemeScope,
+} from '@mui/material/styles';
+
+// The CSS variables props (`scoped`, `colorSchemeNode`, …) are only typed with the CSS variables augmentation.
+const ThemeProvider = MaterialThemeProvider as React.ComponentType<any>;
+
+const appTheme = createTheme({
+  cssVariables: { colorSchemeSelector: 'class' },
+  colorSchemes: { light: true, dark: true },
+});
+const sameVarsTheme = createTheme({
+  cssVariables: { colorSchemeSelector: 'class' },
+  colorSchemes: { light: true, dark: true },
+  components: { MuiButton: { defaultProps: { disableElevation: true } } },
+});
+const promoTheme = createTheme({
+  cssVariables: { colorSchemeSelector: 'class' },
+  colorSchemes: {
+    light: { palette: { primary: { main: '#9c27b0' } } },
+    dark: { palette: { primary: { main: '#ce93d8' } } },
+  },
+});
+const accentTheme = createTheme({
+  cssVariables: { colorSchemeSelector: 'class' },
+  colorSchemes: {
+    light: { palette: { primary: { main: '#9c27b0' }, secondary: { main: '#2e7d32' } } },
+    dark: { palette: { primary: { main: '#ce93d8' }, secondary: { main: '#81c784' } } },
+  },
+});
+const widgetTheme = createTheme({
+  cssVariables: { colorSchemeSelector: 'class' },
+  colorSchemes: {
+    light: { palette: { primary: { main: '#e65100' } } },
+    dark: { palette: { primary: { main: '#ffb74d' } } },
+  },
+});
+const widgetDataTheme = createTheme({
+  cssVariables: { colorSchemeSelector: 'data' },
+  colorSchemes: {
+    light: { palette: { primary: { main: '#e65100' } } },
+    dark: { palette: { primary: { main: '#ffb74d' } } },
+  },
+});
+const forcedDarkTheme = createTheme({
+  cssVariables: { colorSchemeSelector: 'class' },
+  palette: { mode: 'dark', primary: { main: '#f48fb1' } },
+});
+
+// ---------------------------------------------------------------------------
+// Each scenario renders in its own iframe, because root providers write to `:root`.
+
+interface FrameValue {
+  document: Document;
+  window: Window;
+}
+
+const FrameContext = React.createContext<FrameValue | null>(null);
+
+function useFrame() {
+  return React.useContext(FrameContext)!;
+}
+
+let frameCount = 0;
+
+function Frame(props: {
+  children: React.ReactNode;
+  height: number;
+  onReady: (frame: FrameValue) => void;
+}) {
+  const { children, height, onReady } = props;
+  const ref = React.useRef<HTMLIFrameElement>(null);
+  const [frame, setFrame] = React.useState<(FrameValue & { cache: EmotionCache }) | null>(null);
+
+  React.useEffect(() => {
+    const iframe = ref.current!;
+    const init = () => {
+      frameCount += 1;
+      const value = {
+        document: iframe.contentDocument!,
+        window: iframe.contentWindow!,
+        cache: createCache({
+          key: `frame${String.fromCharCode(96 + (frameCount % 26 || 26))}`,
+          container: iframe.contentDocument!.head,
+        }),
+      };
+      setFrame(value);
+      onReady(value);
+    };
+    if (iframe.contentDocument?.readyState === 'complete' && iframe.contentDocument.body) {
+      init();
+      return undefined;
+    }
+    iframe.addEventListener('load', init);
+    return () => iframe.removeEventListener('load', init);
+  }, [onReady]);
+
+  return (
+    <React.Fragment>
+      <iframe
+        ref={ref}
+        title="scenario"
+        srcDoc="<!DOCTYPE html><html><head></head><body style='margin:12px;font-family:Roboto,Helvetica,Arial,sans-serif'></body></html>"
+        style={{ width: '100%', height, border: '1px solid #ccc', borderRadius: 4 }}
+      />
+      {frame &&
+        ReactDOM.createPortal(
+          <CacheProvider value={frame.cache}>
+            <FrameContext.Provider value={frame}>{children}</FrameContext.Provider>
+          </CacheProvider>,
+          frame.document.body,
+        )}
+    </React.Fragment>
+  );
+}
+
+// A root provider of the scenario: it writes to the iframe's `:root`, isolated from the docs' own provider.
+function Root(props: Record<string, any>) {
+  const { document, window } = useFrame();
+  return (
+    <ThemeProvider
+      colorSchemeNode={document.documentElement}
+      documentNode={document}
+      storageWindow={window}
+      storageManager={null}
+      disableNestedContext
+      {...props}
+    />
+  );
+}
+
+// A scoped sibling: isolated from the docs' provider too, and it manages its own mode on its child.
+function ScopedRoot(props: Record<string, any>) {
+  const { document } = useFrame();
+  return (
+    <ThemeProvider documentNode={document} storageManager={null} disableNestedContext {...props} />
+  );
+}
+
+function Swatch({ label }: { label: string }) {
+  return (
+    <Stack direction="row" spacing={1} sx={{ alignItems: 'center', my: 0.5 }} data-inspect={label}>
+      <Button variant="contained" size="small">
+        {label}
+      </Button>
+      <Chip label="secondary" color="secondary" size="small" />
+      <Box
+        sx={{ px: 1, py: 0.5, borderRadius: 1, bgcolor: 'background.paper', color: 'text.primary' }}
+      >
+        paper
+      </Box>
+    </Stack>
+  );
+}
+
+function ModeToggle({ label = 'mode' }: { label?: string }) {
+  const { mode, setMode } = useColorScheme();
+  return (
+    <Button
+      size="small"
+      variant="outlined"
+      onClick={() => setMode(mode === 'dark' ? 'light' : 'dark')}
+    >
+      {label}: {mode ?? '…'}
+    </Button>
+  );
+}
+
+function PortalDemos({ label }: { label: string }) {
+  const { document } = useFrame();
+  const [anchor, setAnchor] = React.useState<HTMLElement | null>(null);
+  const [dialogOpen, setDialogOpen] = React.useState(false);
+  return (
+    <Stack direction="row" spacing={1} sx={{ my: 0.5 }}>
+      <Button size="small" onClick={() => setDialogOpen(true)}>
+        Dialog
+      </Button>
+      <Dialog open={dialogOpen} onClose={() => setDialogOpen(false)} container={document.body}>
+        <DialogContent>
+          <Swatch label={`${label} dialog`} />
+        </DialogContent>
+      </Dialog>
+      <Button size="small" onClick={(event) => setAnchor(event.currentTarget)}>
+        Menu
+      </Button>
+      <Menu
+        anchorEl={anchor}
+        open={!!anchor}
+        onClose={() => setAnchor(null)}
+        container={document.body}
+      >
+        <MenuItem data-inspect={`${label} menu item`} sx={{ color: 'primary.main' }}>
+          Primary item
+        </MenuItem>
+      </Menu>
+      <Tooltip title="Tooltip" slotProps={{ popper: { container: document.body } }}>
+        <Button size="small">Tooltip</Button>
+      </Tooltip>
+    </Stack>
+  );
+}
+
+function Toast({ label }: { label: string }) {
+  const { document } = useFrame();
+  const themeScope = useThemeScope();
+  return ReactDOM.createPortal(
+    <Box
+      {...themeScope}
+      data-inspect={label}
+      sx={{
+        position: 'fixed',
+        right: 8,
+        bottom: 8,
+        p: 1,
+        bgcolor: 'primary.main',
+        color: 'primary.contrastText',
+        borderRadius: 1,
+      }}
+    >
+      {label}
+    </Box>,
+    document.body,
+  );
+}
+
+function Counter() {
+  const [count, setCount] = React.useState(0);
+  return (
+    <Button
+      variant="contained"
+      size="small"
+      onClick={() => setCount(count + 1)}
+      data-inspect="counter"
+    >
+      clicked {count}
+    </Button>
+  );
+}
+
+function ThemeSwitcher() {
+  const [different, setDifferent] = React.useState(false);
+  return (
+    <div>
+      <Button size="small" variant="outlined" onClick={() => setDifferent(!different)}>
+        nested theme: {different ? 'promoTheme (different vars)' : 'sameVarsTheme (same vars)'}
+      </Button>
+      <ThemeProvider theme={different ? promoTheme : sameVarsTheme}>
+        <div data-inspect="nested child">
+          <Counter />
+        </div>
+      </ThemeProvider>
+    </div>
+  );
+}
+
+function Forwards({ className, children }: { className?: string; children: React.ReactNode }) {
+  return (
+    <section className={className} data-inspect="forwards className">
+      {children}
+    </section>
+  );
+}
+
+// It receives `className` from the provider but doesn't render it.
+function DropsClassName({ children }: { children: React.ReactNode }) {
+  return <section data-inspect="drops className">{children}</section>;
+}
+
+// ---------------------------------------------------------------------------
+// Scenarios
+
+interface Scenario {
+  title: string;
+  description: string;
+  code: string;
+  height?: number;
+  render: () => React.ReactNode;
+}
+
+const scenarios: Scenario[] = [
+  {
+    title: '1. Single root provider',
+    description: 'Baseline: variables on :root, no class added to the children.',
+    code: `<ThemeProvider theme={appTheme}>
+  <Swatch />
+</ThemeProvider>`,
+    render: () => (
+      <Root theme={appTheme}>
+        <ModeToggle />
+        <Swatch label="root" />
+      </Root>
+    ),
+  },
+  {
+    title: '2. Two root providers',
+    description:
+      'Both write to :root and the last one wins for both. Logs a warning in development.',
+    code: `<ThemeProvider theme={appTheme}><Swatch /></ThemeProvider>
+<ThemeProvider theme={widgetTheme}><Swatch /></ThemeProvider>`,
+    render: () => (
+      <React.Fragment>
+        <Root theme={appTheme}>
+          <Swatch label="app" />
+        </Root>
+        <Root theme={widgetTheme}>
+          <Swatch label="widget" />
+        </Root>
+      </React.Fragment>
+    ),
+  },
+  {
+    title: '3. Root + scoped sibling',
+    description:
+      'The scoped provider sets all its variables on its child, and has its own mode (toggle both).',
+    code: `<ThemeProvider theme={appTheme}><App /></ThemeProvider>
+<ThemeProvider theme={widgetTheme} scoped="widget">
+  <div><Widget /></div>
+</ThemeProvider>`,
+    height: 220,
+    render: () => (
+      <React.Fragment>
+        <Root theme={appTheme}>
+          <div>
+            <ModeToggle label="app mode" />
+            <Swatch label="app" />
+          </div>
+        </Root>
+        <ScopedRoot theme={widgetTheme} scoped="widget">
+          <div data-inspect="widget child">
+            <ModeToggle label="widget mode" />
+            <Swatch label="widget" />
+          </div>
+        </ScopedRoot>
+      </React.Fragment>
+    ),
+  },
+  {
+    title: '4. Scoped sibling with a data attribute selector',
+    description: 'The color scheme attribute goes on the child too.',
+    code: `<ThemeProvider theme={widgetDataTheme} scoped defaultMode="dark">
+  <div><Widget /></div>
+</ThemeProvider>`,
+    render: () => (
+      <ScopedRoot theme={widgetDataTheme} scoped defaultMode="dark">
+        <div data-inspect="widget child">
+          <ModeToggle label="widget mode" />
+          <Swatch label="widget" />
+        </div>
+      </ScopedRoot>
+    ),
+  },
+  {
+    title: '5. Nested, same variables',
+    description: 'Only component defaults change: the child is left untouched.',
+    code: `<ThemeProvider theme={appTheme}>
+  <ThemeProvider theme={sameVarsTheme}>
+    <div><Swatch /></div>
+  </ThemeProvider>
+</ThemeProvider>`,
+    render: () => (
+      <Root theme={appTheme}>
+        <ThemeProvider theme={sameVarsTheme}>
+          <div data-inspect="nested child">
+            <Swatch label="nested" />
+          </div>
+        </ThemeProvider>
+      </Root>
+    ),
+  },
+  {
+    title: '6. Nested, different variables',
+    description:
+      'The child gets a class that only sets the variables that differ. It follows the outer mode.',
+    code: `<ThemeProvider theme={appTheme}>
+  <Swatch />
+  <ThemeProvider theme={promoTheme}>
+    <div><Swatch /></div>
+  </ThemeProvider>
+</ThemeProvider>`,
+    height: 220,
+    render: () => (
+      <Root theme={appTheme}>
+        <div>
+          <ModeToggle label="outer mode" />
+          <Swatch label="outer" />
+          <ThemeProvider theme={promoTheme}>
+            <div data-inspect="nested child">
+              <Swatch label="nested" />
+            </div>
+          </ThemeProvider>
+        </div>
+      </Root>
+    ),
+  },
+  {
+    title: '7. Nested, children that are not a single element',
+    description:
+      'Several children, a Fragment, text and an array: nothing is applied, and an error is logged in development.',
+    code: `<ThemeProvider theme={promoTheme}>
+  <Swatch />
+  <Swatch />
+</ThemeProvider>
+<ThemeProvider theme={promoTheme}><>…</></ThemeProvider>
+<ThemeProvider theme={promoTheme}>text</ThemeProvider>
+<ThemeProvider theme={promoTheme}>{[<Swatch key="a" />]}</ThemeProvider>`,
+    height: 260,
+    render: () => (
+      <Root theme={appTheme}>
+        <div>
+          <ThemeProvider theme={promoTheme}>
+            <Swatch label="several 1" />
+            <Swatch label="several 2" />
+          </ThemeProvider>
+          <ThemeProvider theme={promoTheme}>
+            <React.Fragment>
+              <Swatch label="fragment 1" />
+              <Swatch label="fragment 2" />
+            </React.Fragment>
+          </ThemeProvider>
+          <ThemeProvider theme={promoTheme}>plain text child</ThemeProvider>
+          <ThemeProvider theme={promoTheme}>{[<Swatch key="a" label="array" />]}</ThemeProvider>
+        </div>
+      </Root>
+    ),
+  },
+  {
+    title: '8. Nested, custom component child',
+    description:
+      'A component that forwards className gets the theme. One that drops it silently keeps the outer theme.',
+    code: `<ThemeProvider theme={promoTheme}>
+  <Forwards><Swatch /></Forwards>
+</ThemeProvider>
+<ThemeProvider theme={promoTheme}>
+  <DropsClassName><Swatch /></DropsClassName>
+</ThemeProvider>`,
+    height: 200,
+    render: () => (
+      <Root theme={appTheme}>
+        <div>
+          <ThemeProvider theme={promoTheme}>
+            <Forwards>
+              <Swatch label="forwards" />
+            </Forwards>
+          </ThemeProvider>
+          <ThemeProvider theme={promoTheme}>
+            <DropsClassName>
+              <Swatch label="drops" />
+            </DropsClassName>
+          </ThemeProvider>
+        </div>
+      </Root>
+    ),
+  },
+  {
+    title: '9. Directly nested providers and a function theme',
+    description:
+      'A provider whose child is another provider passes its class on. The middle theme (primary) and the inner one (secondary) both apply.',
+    code: `<ThemeProvider theme={appTheme}>
+  <ThemeProvider theme={promoTheme}>
+    <ThemeProvider theme={accentTheme}>
+      <div><Swatch /></div>
+    </ThemeProvider>
+  </ThemeProvider>
+  <ThemeProvider theme={promoTheme}>
+    <ThemeProvider theme={(outer) => ({ ...outer })}>
+      <div><Swatch /></div>
+    </ThemeProvider>
+  </ThemeProvider>
+</ThemeProvider>`,
+    height: 200,
+    render: () => (
+      <Root theme={appTheme}>
+        <div>
+          <ThemeProvider theme={promoTheme}>
+            <ThemeProvider theme={accentTheme}>
+              <div data-inspect="a → b → c child">
+                <Swatch label="direct nesting" />
+              </div>
+            </ThemeProvider>
+          </ThemeProvider>
+          <ThemeProvider theme={promoTheme}>
+            <ThemeProvider theme={(outer: object) => ({ ...outer })}>
+              <div data-inspect="function theme child">
+                <Swatch label="function theme" />
+              </div>
+            </ThemeProvider>
+          </ThemeProvider>
+        </div>
+      </Root>
+    ),
+  },
+  {
+    title: '10. Portals in a nested provider',
+    description:
+      'Dialog, Menu and Tooltip apply the class to their own root. useThemeScope() does it for other portals.',
+    code: `<ThemeProvider theme={appTheme}>
+  <ThemeProvider theme={promoTheme}>
+    <div>
+      <Dialog … /> <Menu … /> <Tooltip … />
+      <Toast /> {/* createPortal + useThemeScope() */}
+    </div>
+  </ThemeProvider>
+</ThemeProvider>`,
+    height: 240,
+    render: () => (
+      <Root theme={appTheme}>
+        <div>
+          <ModeToggle label="outer mode" />
+          <ThemeProvider theme={promoTheme}>
+            <div data-inspect="nested child">
+              <PortalDemos label="nested" />
+              <Toast label="toast (nested)" />
+            </div>
+          </ThemeProvider>
+        </div>
+      </Root>
+    ),
+  },
+  {
+    title: '11. Portals in a scoped sibling',
+    description:
+      'Portaled content gets the scope class and the color scheme class of the scoped provider.',
+    code: `<ThemeProvider theme={widgetTheme} scoped>
+  <div>
+    <Dialog … /> <Menu … /> <Tooltip … /> <Toast />
+  </div>
+</ThemeProvider>`,
+    height: 240,
+    render: () => (
+      <ScopedRoot theme={widgetTheme} scoped defaultMode="dark">
+        <div data-inspect="widget child">
+          <ModeToggle label="widget mode" />
+          <PortalDemos label="widget" />
+          <Toast label="toast (scoped)" />
+        </div>
+      </ScopedRoot>
+    ),
+  },
+  {
+    title: '12. Forced single-scheme nested section',
+    description: 'A nested theme with only a dark scheme stays dark whatever the outer mode is.',
+    code: `<ThemeProvider theme={appTheme}>
+  <ThemeProvider theme={forcedDarkTheme}>
+    <div><Swatch /></div>
+  </ThemeProvider>
+</ThemeProvider>`,
+    height: 200,
+    render: () => (
+      <Root theme={appTheme}>
+        <div>
+          <ModeToggle label="outer mode" />
+          <Swatch label="outer" />
+          <ThemeProvider theme={forcedDarkTheme}>
+            <Box data-inspect="forced dark child" sx={{ p: 1, bgcolor: 'background.default' }}>
+              <Swatch label="always dark" />
+            </Box>
+          </ThemeProvider>
+        </div>
+      </Root>
+    ),
+  },
+  {
+    title: '13. Switching between same and different variables',
+    description: 'Click the counter, then switch the nested theme: the count is kept (no remount).',
+    code: `<ThemeProvider theme={appTheme}>
+  <ThemeProvider theme={different ? promoTheme : sameVarsTheme}>
+    <div><Counter /></div>
+  </ThemeProvider>
+</ThemeProvider>`,
+    height: 180,
+    render: () => (
+      <Root theme={appTheme}>
+        <ThemeSwitcher />
+      </Root>
+    ),
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Inspector: reads what ended up in the iframe.
+
+interface Inspection {
+  html: string;
+  rootVars: string;
+  elements: Array<{ label: string; details: string }>;
+  rules: string[];
+}
+
+function inspect(doc: Document): Inspection {
+  const view = doc.defaultView!;
+  const read = (element: Element) => {
+    const style = view.getComputedStyle(element);
+    return `primary ${style.getPropertyValue('--mui-palette-primary-main').trim() || '—'}, color-scheme ${style.colorScheme}`;
+  };
+  const interesting = (element: Element) => {
+    const classes = Array.from(element.classList).filter(
+      (name) => name.startsWith('mui-theme-') || name === 'light' || name === 'dark',
+    );
+    const attributes = Array.from(element.attributes)
+      .filter(
+        (attribute) => attribute.name.startsWith('data-') && attribute.name !== 'data-inspect',
+      )
+      .map((attribute) => `${attribute.name}="${attribute.value}"`);
+    return [...classes.map((name) => `.${name}`), ...attributes].join(' ') || 'no scope class';
+  };
+
+  const rules: string[] = [];
+  Array.from(doc.styleSheets).forEach((sheet) => {
+    try {
+      Array.from(sheet.cssRules).forEach((rule) => {
+        if (rule.cssText.includes('mui-theme-')) {
+          rules.push(rule.cssText.replace(/;\s*/g, ';\n  ').replace(/\{\s*/, '{\n  '));
+        }
+      });
+    } catch {
+      // Cross-origin sheet
+    }
+  });
+
+  return {
+    html: `<html ${interesting(doc.documentElement)}>`,
+    rootVars: read(doc.documentElement),
+    elements: Array.from(doc.querySelectorAll('[data-inspect]')).map((element) => {
+      const scoped = element.closest('[class*="mui-theme-"]');
+      return {
+        label: element.getAttribute('data-inspect')!,
+        details: `${interesting(scoped ?? element)} → ${read(element)}`,
+      };
+    }),
+    rules: Array.from(new Set(rules)),
+  };
+}
+
+function Inspector({ frame }: { frame: FrameValue | null }) {
+  const [info, setInfo] = React.useState<Inspection | null>(null);
+  React.useEffect(() => {
+    if (!frame) {
+      return undefined;
+    }
+    let raf = 0;
+    const update = () => {
+      cancelAnimationFrame(raf);
+      raf = requestAnimationFrame(() => setInfo(inspect(frame.document)));
+    };
+    const observer = new MutationObserver(update);
+    observer.observe(frame.document, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      characterData: true,
+    });
+    update();
+    return () => {
+      observer.disconnect();
+      cancelAnimationFrame(raf);
+    };
+  }, [frame]);
+
+  if (!info) {
+    return null;
+  }
+  return (
+    <Box
+      component="pre"
+      sx={{
+        m: 0,
+        p: 1,
+        fontSize: 11,
+        lineHeight: 1.5,
+        bgcolor: 'grey.100',
+        borderRadius: 1,
+        overflow: 'auto',
+        maxHeight: 320,
+        color: 'grey.900',
+      }}
+    >
+      {`${info.html}\n:root → ${info.rootVars}\n\n`}
+      {info.elements.map((element) => `[${element.label}] ${element.details}\n`).join('')}
+      {info.rules.length ? `\nScoped rules:\n${info.rules.join('\n')}` : '\nNo scoped rules'}
+    </Box>
+  );
+}
+
+function ScenarioCard({ scenario }: { scenario: Scenario }) {
+  const [frame, setFrame] = React.useState<FrameValue | null>(null);
+  return (
+    <Box sx={{ border: '1px solid', borderColor: 'divider', borderRadius: 1, p: 2 }}>
+      <Typography variant="h6" component="h2">
+        {scenario.title}
+      </Typography>
+      <Typography variant="body2" sx={{ mb: 1, color: 'text.secondary' }}>
+        {scenario.description}
+      </Typography>
+      <Box
+        component="pre"
+        sx={{
+          m: 0,
+          mb: 1,
+          p: 1,
+          fontSize: 12,
+          bgcolor: 'grey.900',
+          color: 'grey.100',
+          borderRadius: 1,
+          overflow: 'auto',
+        }}
+      >
+        {scenario.code}
+      </Box>
+      <Box sx={{ display: 'grid', gap: 1, gridTemplateColumns: { xs: '1fr', md: '1fr 1fr' } }}>
+        <Frame height={scenario.height ?? 160} onReady={setFrame}>
+          {scenario.render()}
+        </Frame>
+        <Inspector frame={frame} />
+      </Box>
+    </Box>
+  );
+}
+
+// Captures the MUI warnings and errors of the whole page, since the scenarios share one JS context.
+// It patches the console when the module loads, so it also catches what the first render logs.
+const consoleMessages: string[] = [];
+const consoleListeners = new Set<() => void>();
+if (typeof window !== 'undefined') {
+  (['warn', 'error'] as const).forEach((level) => {
+    // eslint-disable-next-line no-console
+    const original = console[level];
+    // eslint-disable-next-line no-console
+    console[level] = (...args: unknown[]) => {
+      const text = String(args[0]);
+      if (text.startsWith('MUI:') && !consoleMessages.includes(`${level}: ${text}`)) {
+        consoleMessages.push(`${level}: ${text}`);
+        consoleListeners.forEach((listener) => listener());
+      }
+      original(...args);
+    };
+  });
+}
+
+function useMuiConsoleMessages() {
+  return React.useSyncExternalStore(
+    (listener) => {
+      consoleListeners.add(listener);
+      return () => consoleListeners.delete(listener);
+    },
+    () => consoleMessages.length,
+    () => 0,
+  );
+}
+
+export default function ThemeProviderScoping() {
+  useMuiConsoleMessages();
+  const messages = consoleMessages;
+  return (
+    <Box sx={{ p: { xs: 2, md: 4 }, maxWidth: 1400, mx: 'auto' }}>
+      <Typography variant="h4" component="h1" gutterBottom>
+        ThemeProvider scoping playground
+      </Typography>
+      <Typography variant="body2" sx={{ mb: 2 }}>
+        Temporary page for #49581. Each scenario renders in its own iframe. The right column shows
+        what ended up in the iframe: the classes and attributes on the scoped elements, the computed
+        primary color and color scheme, and the generated scoped CSS rules. The scenarios share one
+        JS context, so the root-provider warning shows up even though each iframe has its own
+        `:root`.
+      </Typography>
+      <Box
+        component="pre"
+        sx={{ p: 1, fontSize: 12, bgcolor: 'grey.100', borderRadius: 1, whiteSpace: 'pre-wrap' }}
+      >
+        {messages.length
+          ? `MUI console messages (whole page, each logged once per module):\n${messages.join('\n\n')}`
+          : 'No MUI console messages yet.'}
+      </Box>
+      <Stack spacing={3} sx={{ mt: 2 }}>
+        {scenarios.map((scenario) => (
+          <ScenarioCard key={scenario.title} scenario={scenario} />
+        ))}
+      </Stack>
+    </Box>
+  );
+}

From c27dbba5e4df9ba38f7126888da3fe54dc1484fc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Wed, 28 Oct 2026 00:00:20 +0100
Subject: [PATCH 17/20] [system][material-ui] Make the `scoped` prop a boolean

A string name both made the class readable and suffixed the storage keys. A scoped provider now only stores its mode when `modeStorageKey` or `colorSchemeStorageKey` is set, and the class keeps the `cssVarPrefix`, so the name is no longer needed.
---
 .../css-theme-variables/configuration.md      |  6 ++--
 .../experiments/theme-provider-scoping.tsx    |  4 +--
 .../mui-material/src/styles/ThemeProvider.tsx |  5 ++-
 .../src/styles/ThemeProviderScoped.test.tsx   | 23 +++++--------
 .../src/cssVars/createCssVarsProvider.tsx     | 33 ++++++++-----------
 .../src/cssVars/scopeCssVars.test.ts          | 12 -------
 .../mui-system/src/cssVars/scopeCssVars.ts    |  7 ++--
 7 files changed, 32 insertions(+), 58 deletions(-)

diff --git a/docs/data/material/customization/css-theme-variables/configuration.md b/docs/data/material/customization/css-theme-variables/configuration.md
index 2c17437ad44624..fb9ff1a2f5d49a 100644
--- a/docs/data/material/customization/css-theme-variables/configuration.md
+++ b/docs/data/material/customization/css-theme-variables/configuration.md
@@ -345,7 +345,7 @@ Add the `scoped` prop to the one that should only apply to its child, like an em
   <ThemeProvider theme={appTheme}>
     <App />
   </ThemeProvider>
-  <ThemeProvider theme={widgetTheme} scoped="widget">
+  <ThemeProvider theme={widgetTheme} scoped>
     <div>
       <Widget />
     </div>
@@ -355,8 +355,8 @@ Add the `scoped` prop to the one that should only apply to its child, like an em
 
 A scoped provider sets all of its variables on its child element, and has its own light or dark mode.
 If the theme's `colorSchemeSelector` uses a data attribute, the child also needs to render the `data-*` props it receives.
-To remember that mode across visits, give it a name: when `scoped` is a string, it's added to the class name and to the storage keys of the mode and color scheme, for example `mui-mode-widget`.
-Without a name, the mode isn't stored, so it doesn't overwrite the mode of the page's provider.
+Its mode isn't stored, so it doesn't overwrite the mode of the page's provider.
+To remember it across visits, pass your own `modeStorageKey` and `colorSchemeStorageKey`.
 
 :::info
 A CSS variable that you override on `:root` doesn't reach the elements under a scoped provider that sets it, because the closest declaration wins.
diff --git a/docs/pages/experiments/theme-provider-scoping.tsx b/docs/pages/experiments/theme-provider-scoping.tsx
index 951a6538d3861a..477a1d75b77b96 100644
--- a/docs/pages/experiments/theme-provider-scoping.tsx
+++ b/docs/pages/experiments/theme-provider-scoping.tsx
@@ -332,7 +332,7 @@ const scenarios: Scenario[] = [
     description:
       'The scoped provider sets all its variables on its child, and has its own mode (toggle both).',
     code: `<ThemeProvider theme={appTheme}><App /></ThemeProvider>
-<ThemeProvider theme={widgetTheme} scoped="widget">
+<ThemeProvider theme={widgetTheme} scoped>
   <div><Widget /></div>
 </ThemeProvider>`,
     height: 220,
@@ -344,7 +344,7 @@ const scenarios: Scenario[] = [
             <Swatch label="app" />
           </div>
         </Root>
-        <ScopedRoot theme={widgetTheme} scoped="widget">
+        <ScopedRoot theme={widgetTheme} scoped>
           <div data-inspect="widget child">
             <ModeToggle label="widget mode" />
             <Swatch label="widget" />
diff --git a/packages/mui-material/src/styles/ThemeProvider.tsx b/packages/mui-material/src/styles/ThemeProvider.tsx
index 7e83f965708e51..6eea45a0a3d176 100644
--- a/packages/mui-material/src/styles/ThemeProvider.tsx
+++ b/packages/mui-material/src/styles/ThemeProvider.tsx
@@ -40,11 +40,10 @@ type ThemeProviderCssVariablesProps = CssThemeVariables extends { enabled: true
        * so they don't affect the rest of the page. Use it for a provider that isn't nested in another one,
        * like an embedded widget. Nested providers are scoped automatically when their variables differ.
        * Either way, the provider needs a single child element that renders the `className` it receives.
-       *
-       * A string is used as a readable part of the class name, and to suffix the storage keys.
+       * Its mode is only stored when `modeStorageKey` or `colorSchemeStorageKey` is set.
        * @default false
        */
-      scoped?: boolean | string | undefined;
+      scoped?: boolean | undefined;
     }
   : {};
 
diff --git a/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx b/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
index 008818a2692c76..5a02c8ba9b19a4 100644
--- a/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
+++ b/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
@@ -282,7 +282,7 @@ describe('ThemeProvider with scoped CSS theme variables', () => {
       expect(getComputedStyle(screen.getByTestId('widget')).colorScheme).to.equal('dark');
     });
 
-    it('only uses the storage for a named scoped provider', () => {
+    it('only uses the storage for a scoped provider with storage keys', () => {
       const theme = createTheme({
         cssVariables: { colorSchemeSelector: 'class' },
         colorSchemes: { light: true, dark: true },
@@ -304,24 +304,19 @@ describe('ThemeProvider with scoped CSS theme variables', () => {
           <ThemeProvider theme={theme} scoped storageWindow={storageWindow}>
             <div />
           </ThemeProvider>
-          <ThemeProvider theme={theme} scoped="widget" storageWindow={storageWindow}>
+          <ThemeProvider
+            theme={theme}
+            scoped
+            modeStorageKey="widget-mode"
+            colorSchemeStorageKey="widget-color-scheme"
+            storageWindow={storageWindow}
+          >
             <div />
           </ThemeProvider>
         </React.Fragment>,
       );
       expect(readKeys.length).to.be.greaterThan(0);
-      expect(readKeys.every((key) => key.endsWith('-widget') || key.includes('-widget-'))).to.equal(
-        true,
-      );
-    });
-
-    it('uses the name in the class name', () => {
-      render(
-        <ThemeProvider theme={redTheme} scoped="widget">
-          <div data-testid="widget" />
-        </ThemeProvider>,
-      );
-      expect(screen.getByTestId('widget').className).to.match(/^mui-theme-widget-[a-z0-9]+$/);
+      expect(readKeys.every((key) => key.startsWith('widget-'))).to.equal(true);
     });
 
     it('adds the color scheme attribute to the child', () => {
diff --git a/packages/mui-system/src/cssVars/createCssVarsProvider.tsx b/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
index 7f1436f75417c0..6ada32287b4718 100644
--- a/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
+++ b/packages/mui-system/src/cssVars/createCssVarsProvider.tsx
@@ -125,11 +125,10 @@ export interface CreateCssVarsProviderResult<
          * so they don't affect the rest of the page. Use it for a provider that isn't nested in another one,
          * like an embedded widget. Nested providers are scoped automatically when their variables differ.
          * Either way, the provider needs a single child element that renders the `className` it receives.
-         *
-         * A string is used as a readable part of the class name, and to suffix the storage keys.
+         * Its mode is only stored when `modeStorageKey` or `colorSchemeStorageKey` is set.
          * @default false
          */
-        scoped?: boolean | string | undefined;
+        scoped?: boolean | undefined;
       }
     >,
   ) => React.JSX.Element;
@@ -243,7 +242,6 @@ export default function createCssVarsProvider<
     upperGenerate: (() => CssVarsByColorScheme) | undefined,
     colorSchemeSelector: string | undefined,
     prefix: string,
-    name: string | undefined,
   ) {
     let byUpper = scopedStyleSheetsCache.get(generate);
     if (!byUpper) {
@@ -255,7 +253,7 @@ export default function createCssVarsProvider<
       byOptions = new Map();
       byUpper.set(upperGenerate ?? noUpper, byOptions);
     }
-    const key = `${colorSchemeSelector}|${prefix}|${name}`;
+    const key = `${colorSchemeSelector}|${prefix}`;
     if (!byOptions.has(key)) {
       byOptions.set(
         key,
@@ -264,7 +262,6 @@ export default function createCssVarsProvider<
           upper: upperGenerate?.(),
           colorSchemeSelector,
           prefix,
-          name,
         }),
       );
     }
@@ -280,6 +277,8 @@ export default function createCssVarsProvider<
       children,
       theme: themeProp,
       scoped = false,
+      modeStorageKey = defaultModeStorageKey,
+      colorSchemeStorageKey = defaultColorSchemeStorageKey,
       disableTransitionOnChange = designSystemTransitionOnChange,
       storageManager,
       storageWindow = typeof window === 'undefined' ? undefined : window,
@@ -296,14 +295,8 @@ export default function createCssVarsProvider<
     const ctx = React.useContext(ColorSchemeContext);
     const upperScope = React.useContext(ThemeScopeContext);
     const nested = !!ctx && !disableNestedContext;
-    const scopeName = typeof scoped === 'string' ? scoped : undefined;
     // A scoped provider that isn't nested manages its own color scheme on its element.
-    const isScopedRoot = !nested && !!scoped;
-    const storageKeySuffix = isScopedRoot && scopeName ? `-${scopeName}` : '';
-    const {
-      modeStorageKey = `${defaultModeStorageKey}${storageKeySuffix}`,
-      colorSchemeStorageKey = `${defaultColorSchemeStorageKey}${storageKeySuffix}`,
-    } = props;
+    const isScopedRoot = !nested && scoped;
 
     const initialTheme = React.useMemo(() => {
       if (themeProp) {
@@ -351,9 +344,14 @@ export default function createCssVarsProvider<
       modeStorageKey,
       colorSchemeStorageKey,
       defaultMode,
-      // An unnamed scoped provider would share the storage keys of the page's provider, so it doesn't store its mode.
+      // With the default storage keys, a scoped provider would overwrite the mode of the page's provider.
       storageManager:
-        isScopedRoot && !scopeName && props.storageManager === undefined ? null : storageManager,
+        isScopedRoot &&
+        props.storageManager === undefined &&
+        props.modeStorageKey === undefined &&
+        props.colorSchemeStorageKey === undefined
+          ? null
+          : storageManager,
       storageWindow,
       noSsr,
     });
@@ -561,7 +559,6 @@ export default function createCssVarsProvider<
           upperGenerateCssVarsByColorScheme,
           upperColorSchemeSelector,
           cssVarPrefix,
-          scopeName,
         );
       }
       if (scoped) {
@@ -570,7 +567,6 @@ export default function createCssVarsProvider<
           undefined,
           colorSchemeSelector,
           cssVarPrefix,
-          scopeName,
         );
       }
       return null;
@@ -583,7 +579,6 @@ export default function createCssVarsProvider<
       cssVarPrefix,
       nested,
       scoped,
-      scopeName,
     ]);
 
     const scopeClassName = scope?.className;
@@ -756,7 +751,7 @@ export default function createCssVarsProvider<
     /**
      * If `true`, the CSS theme variables are set on its child element instead of `:root`.
      */
-    scoped: PropTypes.oneOfType([PropTypes.bool, PropTypes.string]),
+    scoped: PropTypes.bool,
     /**
      * The storage manager to be used for storing the mode and color scheme
      * @default using `window.localStorage`
diff --git a/packages/mui-system/src/cssVars/scopeCssVars.test.ts b/packages/mui-system/src/cssVars/scopeCssVars.test.ts
index c7b9e87165c224..c898802716863b 100644
--- a/packages/mui-system/src/cssVars/scopeCssVars.test.ts
+++ b/packages/mui-system/src/cssVars/scopeCssVars.test.ts
@@ -87,25 +87,13 @@ describe('createScopedStyleSheets', () => {
       css: upper,
       colorSchemeSelector: 'data-mui-color-scheme',
       prefix: 'mui',
-      name: 'widget',
     })!;
     const scope = `.${result.className}`;
-    expect(result.className).to.match(/^mui-theme-widget-[a-z0-9]+$/);
     expect(result.styles[2]).to.deep.equal({
       [`${scope}[data-mui-color-scheme="dark"]`]: upper.colorSchemes[1][1],
     });
   });
 
-  it('replaces the characters of the name that are not valid in a class', () => {
-    const result = createScopedStyleSheets({
-      css: upper,
-      colorSchemeSelector: 'class',
-      prefix: 'mui',
-      name: 'my widget.v2',
-    })!;
-    expect(result.className).to.match(/^mui-theme-my-widget-v2-[a-z0-9]+$/);
-  });
-
   it('gives the same class name to the same declarations', () => {
     const options = { css: upper, colorSchemeSelector: 'class', prefix: 'mui' };
     expect(createScopedStyleSheets(options)!.className).to.equal(
diff --git a/packages/mui-system/src/cssVars/scopeCssVars.ts b/packages/mui-system/src/cssVars/scopeCssVars.ts
index ecc4d4c172cc6d..c00479829df56a 100644
--- a/packages/mui-system/src/cssVars/scopeCssVars.ts
+++ b/packages/mui-system/src/cssVars/scopeCssVars.ts
@@ -91,9 +91,8 @@ export function createScopedStyleSheets(options: {
   upper?: CssVarsByColorScheme | undefined;
   colorSchemeSelector: string | undefined;
   prefix: string;
-  name?: string | undefined;
 }) {
-  const { css, upper, colorSchemeSelector, prefix, name } = options;
+  const { css, upper, colorSchemeSelector, prefix } = options;
   const rule = getColorSchemeRule(colorSchemeSelector);
   const [defaultScheme, ...otherSchemes] = css.colorSchemes;
   const upperSchemes = upper ? Object.fromEntries(upper.colorSchemes) : {};
@@ -127,9 +126,7 @@ export function createScopedStyleSheets(options: {
     return null;
   }
 
-  // The name is only there to make the class readable, so characters that aren't valid in a class are replaced.
-  const safeName = name?.replace(/[^a-zA-Z0-9_-]/g, '-');
-  const className = `${prefix ? `${prefix}-` : ''}theme-${safeName ? `${safeName}-` : ''}${hash(
+  const className = `${prefix ? `${prefix}-` : ''}theme-${hash(
     JSON.stringify([root, schemes, rule, !!upper]),
   )}`;
   const scope = `.${className}`;

From 52509bb2f04a08ea6a2520c4cb375e2735ae3c58 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Wed, 28 Oct 2026 00:06:29 +0100
Subject: [PATCH 18/20] [docs] Simplify the ThemeProvider scoping playground

Inspect each scoped element once, show only the palette and color scheme declarations of the scoped rules, size the iframes to their content, merge the portal scenarios, and add a page title.
---
 .../experiments/theme-provider-scoping.tsx    | 522 ++++++++----------
 1 file changed, 241 insertions(+), 281 deletions(-)

diff --git a/docs/pages/experiments/theme-provider-scoping.tsx b/docs/pages/experiments/theme-provider-scoping.tsx
index 477a1d75b77b96..a6f0158f8dbc91 100644
--- a/docs/pages/experiments/theme-provider-scoping.tsx
+++ b/docs/pages/experiments/theme-provider-scoping.tsx
@@ -6,13 +6,12 @@ import createCache, { EmotionCache } from '@emotion/cache';
 import { CacheProvider } from '@emotion/react';
 import Box from '@mui/material/Box';
 import Button from '@mui/material/Button';
-import Chip from '@mui/material/Chip';
 import Dialog from '@mui/material/Dialog';
 import DialogContent from '@mui/material/DialogContent';
 import Menu from '@mui/material/Menu';
 import MenuItem from '@mui/material/MenuItem';
-import Tooltip from '@mui/material/Tooltip';
 import Stack from '@mui/material/Stack';
+import Tooltip from '@mui/material/Tooltip';
 import Typography from '@mui/material/Typography';
 import {
   ThemeProvider as MaterialThemeProvider,
@@ -20,40 +19,36 @@ import {
   useColorScheme,
   useThemeScope,
 } from '@mui/material/styles';
+import { AppLayoutHead as Head } from '@mui/internal-core-docs/AppLayout';
 
 // The CSS variables props (`scoped`, `colorSchemeNode`, …) are only typed with the CSS variables augmentation.
 const ThemeProvider = MaterialThemeProvider as React.ComponentType<any>;
 
-const appTheme = createTheme({
-  cssVariables: { colorSchemeSelector: 'class' },
-  colorSchemes: { light: true, dark: true },
-});
+function createColorTheme(light: object, dark: object) {
+  return createTheme({
+    cssVariables: { colorSchemeSelector: 'class' },
+    colorSchemes: { light: { palette: light }, dark: { palette: dark } },
+  });
+}
+
+const appTheme = createColorTheme({}, {});
 const sameVarsTheme = createTheme({
   cssVariables: { colorSchemeSelector: 'class' },
   colorSchemes: { light: true, dark: true },
   components: { MuiButton: { defaultProps: { disableElevation: true } } },
 });
-const promoTheme = createTheme({
-  cssVariables: { colorSchemeSelector: 'class' },
-  colorSchemes: {
-    light: { palette: { primary: { main: '#9c27b0' } } },
-    dark: { palette: { primary: { main: '#ce93d8' } } },
-  },
-});
-const accentTheme = createTheme({
-  cssVariables: { colorSchemeSelector: 'class' },
-  colorSchemes: {
-    light: { palette: { primary: { main: '#9c27b0' }, secondary: { main: '#2e7d32' } } },
-    dark: { palette: { primary: { main: '#ce93d8' }, secondary: { main: '#81c784' } } },
-  },
-});
-const widgetTheme = createTheme({
-  cssVariables: { colorSchemeSelector: 'class' },
-  colorSchemes: {
-    light: { palette: { primary: { main: '#e65100' } } },
-    dark: { palette: { primary: { main: '#ffb74d' } } },
-  },
-});
+const promoTheme = createColorTheme(
+  { primary: { main: '#9c27b0' } },
+  { primary: { main: '#ce93d8' } },
+);
+const accentTheme = createColorTheme(
+  { primary: { main: '#9c27b0' }, secondary: { main: '#2e7d32' } },
+  { primary: { main: '#ce93d8' }, secondary: { main: '#81c784' } },
+);
+const widgetTheme = createColorTheme(
+  { primary: { main: '#e65100' } },
+  { primary: { main: '#ffb74d' } },
+);
 const widgetDataTheme = createTheme({
   cssVariables: { colorSchemeSelector: 'data' },
   colorSchemes: {
@@ -82,36 +77,41 @@ function useFrame() {
 
 let frameCount = 0;
 
-function Frame(props: {
-  children: React.ReactNode;
-  height: number;
-  onReady: (frame: FrameValue) => void;
-}) {
-  const { children, height, onReady } = props;
+function Frame(props: { children: React.ReactNode; onReady: (frame: FrameValue) => void }) {
+  const { children, onReady } = props;
   const ref = React.useRef<HTMLIFrameElement>(null);
   const [frame, setFrame] = React.useState<(FrameValue & { cache: EmotionCache }) | null>(null);
+  const [height, setHeight] = React.useState(80);
 
   React.useEffect(() => {
     const iframe = ref.current!;
+    let observer: ResizeObserver | undefined;
     const init = () => {
+      const doc = iframe.contentDocument!;
       frameCount += 1;
       const value = {
-        document: iframe.contentDocument!,
+        document: doc,
         window: iframe.contentWindow!,
         cache: createCache({
           key: `frame${String.fromCharCode(96 + (frameCount % 26 || 26))}`,
-          container: iframe.contentDocument!.head,
+          container: doc.head,
         }),
       };
+      // The iframe grows with its content, plus some room for menus and tooltips.
+      observer = new ResizeObserver(() => setHeight(doc.body.scrollHeight + 24));
+      observer.observe(doc.body);
       setFrame(value);
       onReady(value);
     };
     if (iframe.contentDocument?.readyState === 'complete' && iframe.contentDocument.body) {
       init();
-      return undefined;
+    } else {
+      iframe.addEventListener('load', init);
     }
-    iframe.addEventListener('load', init);
-    return () => iframe.removeEventListener('load', init);
+    return () => {
+      iframe.removeEventListener('load', init);
+      observer?.disconnect();
+    };
   }, [onReady]);
 
   return (
@@ -148,27 +148,17 @@ function Root(props: Record<string, any>) {
   );
 }
 
-// A scoped sibling: isolated from the docs' provider too, and it manages its own mode on its child.
+// A scoped sibling: isolated from the docs' provider too, it manages its own mode on its child.
 function ScopedRoot(props: Record<string, any>) {
   const { document } = useFrame();
-  return (
-    <ThemeProvider documentNode={document} storageManager={null} disableNestedContext {...props} />
-  );
+  return <ThemeProvider documentNode={document} disableNestedContext scoped {...props} />;
 }
 
 function Swatch({ label }: { label: string }) {
   return (
-    <Stack direction="row" spacing={1} sx={{ alignItems: 'center', my: 0.5 }} data-inspect={label}>
-      <Button variant="contained" size="small">
-        {label}
-      </Button>
-      <Chip label="secondary" color="secondary" size="small" />
-      <Box
-        sx={{ px: 1, py: 0.5, borderRadius: 1, bgcolor: 'background.paper', color: 'text.primary' }}
-      >
-        paper
-      </Box>
-    </Stack>
+    <Button variant="contained" size="small" sx={{ m: 0.5 }}>
+      {label}
+    </Button>
   );
 }
 
@@ -178,6 +168,7 @@ function ModeToggle({ label = 'mode' }: { label?: string }) {
     <Button
       size="small"
       variant="outlined"
+      sx={{ m: 0.5 }}
       onClick={() => setMode(mode === 'dark' ? 'light' : 'dark')}
     >
       {label}: {mode ?? '…'}
@@ -185,18 +176,19 @@ function ModeToggle({ label = 'mode' }: { label?: string }) {
   );
 }
 
-function PortalDemos({ label }: { label: string }) {
+function Portals({ label }: { label: string }) {
   const { document } = useFrame();
+  const themeScope = useThemeScope();
   const [anchor, setAnchor] = React.useState<HTMLElement | null>(null);
   const [dialogOpen, setDialogOpen] = React.useState(false);
   return (
-    <Stack direction="row" spacing={1} sx={{ my: 0.5 }}>
+    <div>
       <Button size="small" onClick={() => setDialogOpen(true)}>
         Dialog
       </Button>
       <Dialog open={dialogOpen} onClose={() => setDialogOpen(false)} container={document.body}>
-        <DialogContent>
-          <Swatch label={`${label} dialog`} />
+        <DialogContent data-inspect={`${label}: dialog`}>
+          <Swatch label="in dialog" />
         </DialogContent>
       </Dialog>
       <Button size="small" onClick={(event) => setAnchor(event.currentTarget)}>
@@ -208,49 +200,31 @@ function PortalDemos({ label }: { label: string }) {
         onClose={() => setAnchor(null)}
         container={document.body}
       >
-        <MenuItem data-inspect={`${label} menu item`} sx={{ color: 'primary.main' }}>
+        <MenuItem data-inspect={`${label}: menu item`} sx={{ color: 'primary.main' }}>
           Primary item
         </MenuItem>
       </Menu>
       <Tooltip title="Tooltip" slotProps={{ popper: { container: document.body } }}>
         <Button size="small">Tooltip</Button>
       </Tooltip>
-    </Stack>
-  );
-}
-
-function Toast({ label }: { label: string }) {
-  const { document } = useFrame();
-  const themeScope = useThemeScope();
-  return ReactDOM.createPortal(
-    <Box
-      {...themeScope}
-      data-inspect={label}
-      sx={{
-        position: 'fixed',
-        right: 8,
-        bottom: 8,
-        p: 1,
-        bgcolor: 'primary.main',
-        color: 'primary.contrastText',
-        borderRadius: 1,
-      }}
-    >
-      {label}
-    </Box>,
-    document.body,
+      {ReactDOM.createPortal(
+        <Box
+          {...themeScope}
+          data-inspect={`${label}: createPortal + useThemeScope()`}
+          sx={{ p: 0.5 }}
+        >
+          <Swatch label={`${label} portal`} />
+        </Box>,
+        document.body,
+      )}
+    </div>
   );
 }
 
 function Counter() {
   const [count, setCount] = React.useState(0);
   return (
-    <Button
-      variant="contained"
-      size="small"
-      onClick={() => setCount(count + 1)}
-      data-inspect="counter"
-    >
+    <Button variant="contained" size="small" sx={{ m: 0.5 }} onClick={() => setCount(count + 1)}>
       clicked {count}
     </Button>
   );
@@ -261,7 +235,7 @@ function ThemeSwitcher() {
   return (
     <div>
       <Button size="small" variant="outlined" onClick={() => setDifferent(!different)}>
-        nested theme: {different ? 'promoTheme (different vars)' : 'sameVarsTheme (same vars)'}
+        nested theme: {different ? 'promoTheme' : 'sameVarsTheme'}
       </Button>
       <ThemeProvider theme={different ? promoTheme : sameVarsTheme}>
         <div data-inspect="nested child">
@@ -292,59 +266,61 @@ interface Scenario {
   title: string;
   description: string;
   code: string;
-  height?: number;
   render: () => React.ReactNode;
 }
 
 const scenarios: Scenario[] = [
   {
     title: '1. Single root provider',
-    description: 'Baseline: variables on :root, no class added to the children.',
+    description: 'Baseline: variables on :root, nothing added to the children.',
     code: `<ThemeProvider theme={appTheme}>
-  <Swatch />
+  <Button />
 </ThemeProvider>`,
     render: () => (
       <Root theme={appTheme}>
-        <ModeToggle />
-        <Swatch label="root" />
+        <div data-inspect="child">
+          <Swatch label="root" />
+        </div>
       </Root>
     ),
   },
   {
     title: '2. Two root providers',
     description:
-      'Both write to :root and the last one wins for both. Logs a warning in development.',
-    code: `<ThemeProvider theme={appTheme}><Swatch /></ThemeProvider>
-<ThemeProvider theme={widgetTheme}><Swatch /></ThemeProvider>`,
+      'Both write to :root, and the last one wins for both. Logs a warning in development.',
+    code: `<ThemeProvider theme={appTheme}><Button /></ThemeProvider>
+<ThemeProvider theme={widgetTheme}><Button /></ThemeProvider>`,
     render: () => (
       <React.Fragment>
         <Root theme={appTheme}>
-          <Swatch label="app" />
+          <div data-inspect="app child">
+            <Swatch label="app" />
+          </div>
         </Root>
         <Root theme={widgetTheme}>
-          <Swatch label="widget" />
+          <div data-inspect="widget child">
+            <Swatch label="widget" />
+          </div>
         </Root>
       </React.Fragment>
     ),
   },
   {
     title: '3. Root + scoped sibling',
-    description:
-      'The scoped provider sets all its variables on its child, and has its own mode (toggle both).',
+    description: 'The scoped provider sets all its variables on its child, and has its own mode.',
     code: `<ThemeProvider theme={appTheme}><App /></ThemeProvider>
 <ThemeProvider theme={widgetTheme} scoped>
   <div><Widget /></div>
 </ThemeProvider>`,
-    height: 220,
     render: () => (
       <React.Fragment>
         <Root theme={appTheme}>
-          <div>
+          <div data-inspect="app child">
             <ModeToggle label="app mode" />
             <Swatch label="app" />
           </div>
         </Root>
-        <ScopedRoot theme={widgetTheme} scoped>
+        <ScopedRoot theme={widgetTheme}>
           <div data-inspect="widget child">
             <ModeToggle label="widget mode" />
             <Swatch label="widget" />
@@ -360,9 +336,8 @@ const scenarios: Scenario[] = [
   <div><Widget /></div>
 </ThemeProvider>`,
     render: () => (
-      <ScopedRoot theme={widgetDataTheme} scoped defaultMode="dark">
+      <ScopedRoot theme={widgetDataTheme} defaultMode="dark">
         <div data-inspect="widget child">
-          <ModeToggle label="widget mode" />
           <Swatch label="widget" />
         </div>
       </ScopedRoot>
@@ -373,7 +348,7 @@ const scenarios: Scenario[] = [
     description: 'Only component defaults change: the child is left untouched.',
     code: `<ThemeProvider theme={appTheme}>
   <ThemeProvider theme={sameVarsTheme}>
-    <div><Swatch /></div>
+    <div><Button /></div>
   </ThemeProvider>
 </ThemeProvider>`,
     render: () => (
@@ -391,15 +366,14 @@ const scenarios: Scenario[] = [
     description:
       'The child gets a class that only sets the variables that differ. It follows the outer mode.',
     code: `<ThemeProvider theme={appTheme}>
-  <Swatch />
+  <Button />
   <ThemeProvider theme={promoTheme}>
-    <div><Swatch /></div>
+    <div><Button /></div>
   </ThemeProvider>
 </ThemeProvider>`,
-    height: 220,
     render: () => (
       <Root theme={appTheme}>
-        <div>
+        <div data-inspect="outer child">
           <ModeToggle label="outer mode" />
           <Swatch label="outer" />
           <ThemeProvider theme={promoTheme}>
@@ -414,15 +388,11 @@ const scenarios: Scenario[] = [
   {
     title: '7. Nested, children that are not a single element',
     description:
-      'Several children, a Fragment, text and an array: nothing is applied, and an error is logged in development.',
-    code: `<ThemeProvider theme={promoTheme}>
-  <Swatch />
-  <Swatch />
-</ThemeProvider>
+      'Several children, a Fragment, text and an array: the rule is generated, but no element gets the class, and an error is logged in development.',
+    code: `<ThemeProvider theme={promoTheme}><Button /><Button /></ThemeProvider>
 <ThemeProvider theme={promoTheme}><>…</></ThemeProvider>
 <ThemeProvider theme={promoTheme}>text</ThemeProvider>
-<ThemeProvider theme={promoTheme}>{[<Swatch key="a" />]}</ThemeProvider>`,
-    height: 260,
+<ThemeProvider theme={promoTheme}>{[<Button key="a" />]}</ThemeProvider>`,
     render: () => (
       <Root theme={appTheme}>
         <div>
@@ -436,7 +406,7 @@ const scenarios: Scenario[] = [
               <Swatch label="fragment 2" />
             </React.Fragment>
           </ThemeProvider>
-          <ThemeProvider theme={promoTheme}>plain text child</ThemeProvider>
+          <ThemeProvider theme={promoTheme}>text</ThemeProvider>
           <ThemeProvider theme={promoTheme}>{[<Swatch key="a" label="array" />]}</ThemeProvider>
         </div>
       </Root>
@@ -445,14 +415,13 @@ const scenarios: Scenario[] = [
   {
     title: '8. Nested, custom component child',
     description:
-      'A component that forwards className gets the theme. One that drops it silently keeps the outer theme.',
+      'A component that renders the className it receives gets the theme. One that drops it silently keeps the outer theme.',
     code: `<ThemeProvider theme={promoTheme}>
-  <Forwards><Swatch /></Forwards>
+  <Forwards><Button /></Forwards>
 </ThemeProvider>
 <ThemeProvider theme={promoTheme}>
-  <DropsClassName><Swatch /></DropsClassName>
+  <DropsClassName><Button /></DropsClassName>
 </ThemeProvider>`,
-    height: 200,
     render: () => (
       <Root theme={appTheme}>
         <div>
@@ -473,33 +442,33 @@ const scenarios: Scenario[] = [
   {
     title: '9. Directly nested providers and a function theme',
     description:
-      'A provider whose child is another provider passes its class on. The middle theme (primary) and the inner one (secondary) both apply.',
-    code: `<ThemeProvider theme={appTheme}>
-  <ThemeProvider theme={promoTheme}>
-    <ThemeProvider theme={accentTheme}>
-      <div><Swatch /></div>
-    </ThemeProvider>
+      'A provider whose child is another provider passes its class on: the middle theme (primary) and the inner one (secondary) both apply.',
+    code: `<ThemeProvider theme={promoTheme}>
+  <ThemeProvider theme={accentTheme}>
+    <div><Button /></div>
   </ThemeProvider>
-  <ThemeProvider theme={promoTheme}>
-    <ThemeProvider theme={(outer) => ({ ...outer })}>
-      <div><Swatch /></div>
-    </ThemeProvider>
+</ThemeProvider>
+<ThemeProvider theme={promoTheme}>
+  <ThemeProvider theme={(outer) => ({ ...outer })}>
+    <div><Button /></div>
   </ThemeProvider>
 </ThemeProvider>`,
-    height: 200,
     render: () => (
       <Root theme={appTheme}>
         <div>
           <ThemeProvider theme={promoTheme}>
             <ThemeProvider theme={accentTheme}>
-              <div data-inspect="a → b → c child">
+              <div data-inspect="promo → accent child">
                 <Swatch label="direct nesting" />
+                <Button variant="contained" color="secondary" size="small" sx={{ m: 0.5 }}>
+                  secondary
+                </Button>
               </div>
             </ThemeProvider>
           </ThemeProvider>
           <ThemeProvider theme={promoTheme}>
             <ThemeProvider theme={(outer: object) => ({ ...outer })}>
-              <div data-inspect="function theme child">
+              <div data-inspect="promo → function theme child">
                 <Swatch label="function theme" />
               </div>
             </ThemeProvider>
@@ -509,66 +478,47 @@ const scenarios: Scenario[] = [
     ),
   },
   {
-    title: '10. Portals in a nested provider',
+    title: '10. Portals',
     description:
-      'Dialog, Menu and Tooltip apply the class to their own root. useThemeScope() does it for other portals.',
+      'Dialog, Menu and Tooltip apply the scope to their own root, in a nested provider and in a scoped sibling. useThemeScope() does it for other portals.',
     code: `<ThemeProvider theme={appTheme}>
   <ThemeProvider theme={promoTheme}>
-    <div>
-      <Dialog … /> <Menu … /> <Tooltip … />
-      <Toast /> {/* createPortal + useThemeScope() */}
-    </div>
+    <div><Dialog /><Menu /><Tooltip /><Toast /></div>
   </ThemeProvider>
+</ThemeProvider>
+<ThemeProvider theme={widgetTheme} scoped>
+  <div><Dialog /><Menu /><Tooltip /><Toast /></div>
 </ThemeProvider>`,
-    height: 240,
     render: () => (
-      <Root theme={appTheme}>
-        <div>
-          <ModeToggle label="outer mode" />
+      <React.Fragment>
+        <Root theme={appTheme}>
           <ThemeProvider theme={promoTheme}>
             <div data-inspect="nested child">
-              <PortalDemos label="nested" />
-              <Toast label="toast (nested)" />
+              <Portals label="nested" />
             </div>
           </ThemeProvider>
-        </div>
-      </Root>
-    ),
-  },
-  {
-    title: '11. Portals in a scoped sibling',
-    description:
-      'Portaled content gets the scope class and the color scheme class of the scoped provider.',
-    code: `<ThemeProvider theme={widgetTheme} scoped>
-  <div>
-    <Dialog … /> <Menu … /> <Tooltip … /> <Toast />
-  </div>
-</ThemeProvider>`,
-    height: 240,
-    render: () => (
-      <ScopedRoot theme={widgetTheme} scoped defaultMode="dark">
-        <div data-inspect="widget child">
-          <ModeToggle label="widget mode" />
-          <PortalDemos label="widget" />
-          <Toast label="toast (scoped)" />
-        </div>
-      </ScopedRoot>
+        </Root>
+        <ScopedRoot theme={widgetTheme} defaultMode="dark">
+          <div data-inspect="scoped child">
+            <ModeToggle label="scoped mode" />
+            <Portals label="scoped" />
+          </div>
+        </ScopedRoot>
+      </React.Fragment>
     ),
   },
   {
-    title: '12. Forced single-scheme nested section',
+    title: '11. Forced single-scheme nested section',
     description: 'A nested theme with only a dark scheme stays dark whatever the outer mode is.',
     code: `<ThemeProvider theme={appTheme}>
   <ThemeProvider theme={forcedDarkTheme}>
-    <div><Swatch /></div>
+    <div><Button /></div>
   </ThemeProvider>
 </ThemeProvider>`,
-    height: 200,
     render: () => (
       <Root theme={appTheme}>
-        <div>
+        <div data-inspect="outer child">
           <ModeToggle label="outer mode" />
-          <Swatch label="outer" />
           <ThemeProvider theme={forcedDarkTheme}>
             <Box data-inspect="forced dark child" sx={{ p: 1, bgcolor: 'background.default' }}>
               <Swatch label="always dark" />
@@ -579,14 +529,14 @@ const scenarios: Scenario[] = [
     ),
   },
   {
-    title: '13. Switching between same and different variables',
-    description: 'Click the counter, then switch the nested theme: the count is kept (no remount).',
+    title: '12. Switching between same and different variables',
+    description:
+      'Click the counter, then switch the nested theme: the count is kept, so nothing remounts.',
     code: `<ThemeProvider theme={appTheme}>
   <ThemeProvider theme={different ? promoTheme : sameVarsTheme}>
     <div><Counter /></div>
   </ThemeProvider>
 </ThemeProvider>`,
-    height: 180,
     render: () => (
       <Root theme={appTheme}>
         <ThemeSwitcher />
@@ -598,60 +548,79 @@ const scenarios: Scenario[] = [
 // ---------------------------------------------------------------------------
 // Inspector: reads what ended up in the iframe.
 
-interface Inspection {
-  html: string;
-  rootVars: string;
-  elements: Array<{ label: string; details: string }>;
-  rules: string[];
+const interestingDeclaration = /color-scheme|--mui-palette-(primary|secondary)-main:/;
+
+function describeRule(cssText: string) {
+  const [selector, body = ''] = cssText.split('{');
+  const declarations = body
+    .replace('}', '')
+    .split(';')
+    .map((declaration) => declaration.trim())
+    .filter(Boolean);
+  const shown = declarations.filter((declaration) => interestingDeclaration.test(declaration));
+  const more = declarations.length - shown.length;
+  return [
+    `${selector.trim()} {`,
+    ...shown.map((declaration) => `  ${declaration};`),
+    ...(more ? [`  + ${more} more declarations`] : []),
+    '}',
+  ].join('\n');
 }
 
-function inspect(doc: Document): Inspection {
+function inspect(doc: Document) {
   const view = doc.defaultView!;
-  const read = (element: Element) => {
+  const values = (element: Element) => {
     const style = view.getComputedStyle(element);
-    return `primary ${style.getPropertyValue('--mui-palette-primary-main').trim() || '—'}, color-scheme ${style.colorScheme}`;
+    const primary = style.getPropertyValue('--mui-palette-primary-main').trim() || '—';
+    return `primary ${primary}, color-scheme ${style.colorScheme}`;
   };
-  const interesting = (element: Element) => {
-    const classes = Array.from(element.classList).filter(
-      (name) => name.startsWith('mui-theme-') || name === 'light' || name === 'dark',
-    );
+  const scope = (element: Element) => {
+    const classes = Array.from(element.classList)
+      .filter((name) => name.startsWith('mui-theme-') || name === 'light' || name === 'dark')
+      .map((name) => `.${name}`);
     const attributes = Array.from(element.attributes)
-      .filter(
-        (attribute) => attribute.name.startsWith('data-') && attribute.name !== 'data-inspect',
-      )
-      .map((attribute) => `${attribute.name}="${attribute.value}"`);
-    return [...classes.map((name) => `.${name}`), ...attributes].join(' ') || 'no scope class';
+      .filter(({ name }) => name.startsWith('data-') && name !== 'data-inspect')
+      .map(({ name, value }) => `${name}="${value}"`);
+    return [...classes, ...attributes].join(' ') || 'no scope';
   };
 
-  const rules: string[] = [];
+  const ruleTexts = new Set<string>();
   Array.from(doc.styleSheets).forEach((sheet) => {
-    try {
-      Array.from(sheet.cssRules).forEach((rule) => {
-        if (rule.cssText.includes('mui-theme-')) {
-          rules.push(rule.cssText.replace(/;\s*/g, ';\n  ').replace(/\{\s*/, '{\n  '));
-        }
-      });
-    } catch {
-      // Cross-origin sheet
+    Array.from(sheet.cssRules).forEach((rule) => {
+      if (rule.cssText.includes('mui-theme-')) {
+        ruleTexts.add(rule.cssText);
+      }
+    });
+  });
+  const applied: string[] = [];
+  let unused = 0;
+  ruleTexts.forEach((cssText) => {
+    const className = cssText.match(/mui-theme-[a-z0-9]+/)?.[0];
+    if (className && doc.querySelector(`.${className}`)) {
+      applied.push(describeRule(cssText));
+    } else {
+      unused += 1;
     }
   });
 
-  return {
-    html: `<html ${interesting(doc.documentElement)}>`,
-    rootVars: read(doc.documentElement),
-    elements: Array.from(doc.querySelectorAll('[data-inspect]')).map((element) => {
-      const scoped = element.closest('[class*="mui-theme-"]');
-      return {
-        label: element.getAttribute('data-inspect')!,
-        details: `${interesting(scoped ?? element)} → ${read(element)}`,
-      };
-    }),
-    rules: Array.from(new Set(rules)),
-  };
+  const elements = Array.from(doc.querySelectorAll('[data-inspect]')).map((element) => {
+    const scoped = element.closest('[class*="mui-theme-"]') ?? element;
+    return `[${element.getAttribute('data-inspect')}] ${scope(scoped)} → ${values(element)}`;
+  });
+
+  return [
+    `<html> ${scope(doc.documentElement)}`,
+    `:root → ${values(doc.documentElement)}`,
+    '',
+    ...elements,
+    '',
+    applied.length ? `Scoped rules:\n${applied.join('\n')}` : 'No scoped rules applied',
+    unused ? `\n${unused} rule(s) generated, but no element has the class` : '',
+  ].join('\n');
 }
 
 function Inspector({ frame }: { frame: FrameValue | null }) {
-  const [info, setInfo] = React.useState<Inspection | null>(null);
+  const [text, setText] = React.useState('');
   React.useEffect(() => {
     if (!frame) {
       return undefined;
@@ -659,15 +628,10 @@ function Inspector({ frame }: { frame: FrameValue | null }) {
     let raf = 0;
     const update = () => {
       cancelAnimationFrame(raf);
-      raf = requestAnimationFrame(() => setInfo(inspect(frame.document)));
+      raf = requestAnimationFrame(() => setText(inspect(frame.document)));
     };
     const observer = new MutationObserver(update);
-    observer.observe(frame.document, {
-      subtree: true,
-      childList: true,
-      attributes: true,
-      characterData: true,
-    });
+    observer.observe(frame.document, { subtree: true, childList: true, attributes: true });
     update();
     return () => {
       observer.disconnect();
@@ -675,9 +639,6 @@ function Inspector({ frame }: { frame: FrameValue | null }) {
     };
   }, [frame]);
 
-  if (!info) {
-    return null;
-  }
   return (
     <Box
       component="pre"
@@ -687,15 +648,12 @@ function Inspector({ frame }: { frame: FrameValue | null }) {
         fontSize: 11,
         lineHeight: 1.5,
         bgcolor: 'grey.100',
+        color: 'grey.900',
         borderRadius: 1,
         overflow: 'auto',
-        maxHeight: 320,
-        color: 'grey.900',
       }}
     >
-      {`${info.html}\n:root → ${info.rootVars}\n\n`}
-      {info.elements.map((element) => `[${element.label}] ${element.details}\n`).join('')}
-      {info.rules.length ? `\nScoped rules:\n${info.rules.join('\n')}` : '\nNo scoped rules'}
+      {text}
     </Box>
   );
 }
@@ -710,25 +668,24 @@ function ScenarioCard({ scenario }: { scenario: Scenario }) {
       <Typography variant="body2" sx={{ mb: 1, color: 'text.secondary' }}>
         {scenario.description}
       </Typography>
-      <Box
-        component="pre"
-        sx={{
-          m: 0,
-          mb: 1,
-          p: 1,
-          fontSize: 12,
-          bgcolor: 'grey.900',
-          color: 'grey.100',
-          borderRadius: 1,
-          overflow: 'auto',
-        }}
-      >
-        {scenario.code}
-      </Box>
       <Box sx={{ display: 'grid', gap: 1, gridTemplateColumns: { xs: '1fr', md: '1fr 1fr' } }}>
-        <Frame height={scenario.height ?? 160} onReady={setFrame}>
-          {scenario.render()}
-        </Frame>
+        <Stack spacing={1}>
+          <Box
+            component="pre"
+            sx={{
+              m: 0,
+              p: 1,
+              fontSize: 12,
+              bgcolor: 'grey.900',
+              color: 'grey.100',
+              borderRadius: 1,
+              overflow: 'auto',
+            }}
+          >
+            {scenario.code}
+          </Box>
+          <Frame onReady={setFrame}>{scenario.render()}</Frame>
+        </Stack>
         <Inspector frame={frame} />
       </Box>
     </Box>
@@ -745,9 +702,9 @@ if (typeof window !== 'undefined') {
     const original = console[level];
     // eslint-disable-next-line no-console
     console[level] = (...args: unknown[]) => {
-      const text = String(args[0]);
-      if (text.startsWith('MUI:') && !consoleMessages.includes(`${level}: ${text}`)) {
-        consoleMessages.push(`${level}: ${text}`);
+      const text = `${level}: ${String(args[0])}`;
+      if (String(args[0]).startsWith('MUI:') && !consoleMessages.includes(text)) {
+        consoleMessages.push(text);
         consoleListeners.forEach((listener) => listener());
       }
       original(...args);
@@ -755,8 +712,8 @@ if (typeof window !== 'undefined') {
   });
 }
 
-function useMuiConsoleMessages() {
-  return React.useSyncExternalStore(
+function useConsoleMessages() {
+  React.useSyncExternalStore(
     (listener) => {
       consoleListeners.add(listener);
       return () => consoleListeners.delete(listener);
@@ -764,36 +721,39 @@ function useMuiConsoleMessages() {
     () => consoleMessages.length,
     () => 0,
   );
+  return consoleMessages;
 }
 
 export default function ThemeProviderScoping() {
-  useMuiConsoleMessages();
-  const messages = consoleMessages;
+  const messages = useConsoleMessages();
   return (
-    <Box sx={{ p: { xs: 2, md: 4 }, maxWidth: 1400, mx: 'auto' }}>
-      <Typography variant="h4" component="h1" gutterBottom>
-        ThemeProvider scoping playground
-      </Typography>
-      <Typography variant="body2" sx={{ mb: 2 }}>
-        Temporary page for #49581. Each scenario renders in its own iframe. The right column shows
-        what ended up in the iframe: the classes and attributes on the scoped elements, the computed
-        primary color and color scheme, and the generated scoped CSS rules. The scenarios share one
-        JS context, so the root-provider warning shows up even though each iframe has its own
-        `:root`.
-      </Typography>
-      <Box
-        component="pre"
-        sx={{ p: 1, fontSize: 12, bgcolor: 'grey.100', borderRadius: 1, whiteSpace: 'pre-wrap' }}
-      >
-        {messages.length
-          ? `MUI console messages (whole page, each logged once per module):\n${messages.join('\n\n')}`
-          : 'No MUI console messages yet.'}
+    <React.Fragment>
+      <Head title="ThemeProvider scoping playground" description="" />
+      <Box sx={{ p: { xs: 2, md: 4 }, maxWidth: 1400, mx: 'auto' }}>
+        <Typography variant="h4" component="h1" gutterBottom>
+          ThemeProvider scoping playground
+        </Typography>
+        <Typography variant="body2" sx={{ mb: 2 }}>
+          Temporary page for #49581. Each scenario renders in its own iframe. The right column shows
+          what ended up there: the scope classes and attributes, the computed primary color and
+          color scheme, and the scoped CSS rules (palette and color scheme declarations only). The
+          scenarios share one JS context, so the root provider warning shows up even though each
+          iframe has its own <code>:root</code>.
+        </Typography>
+        <Box
+          component="pre"
+          sx={{ p: 1, fontSize: 12, bgcolor: 'grey.100', borderRadius: 1, whiteSpace: 'pre-wrap' }}
+        >
+          {messages.length
+            ? `MUI console messages (whole page):\n${messages.join('\n\n')}`
+            : 'No MUI console messages yet.'}
+        </Box>
+        <Stack spacing={3} sx={{ mt: 2 }}>
+          {scenarios.map((scenario) => (
+            <ScenarioCard key={scenario.title} scenario={scenario} />
+          ))}
+        </Stack>
       </Box>
-      <Stack spacing={3} sx={{ mt: 2 }}>
-        {scenarios.map((scenario) => (
-          <ScenarioCard key={scenario.title} scenario={scenario} />
-        ))}
-      </Stack>
-    </Box>
+    </React.Fragment>
   );
 }

From e4e9e348db965a30f1fbadc247349573cbdfe9cc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Wed, 28 Oct 2026 00:09:24 +0100
Subject: [PATCH 19/20] [docs] Finish the ThemeProvider scoping playground
 cleanup

Drop the console panel and its console patch, merge the data attribute scoped sibling into the scoped siblings scenario and the same-variables case into the theme switch, show the secondary color in the inspector, and key the Emotion caches with React.useId().
---
 .../experiments/theme-provider-scoping.tsx    | 124 +++++-------------
 1 file changed, 30 insertions(+), 94 deletions(-)

diff --git a/docs/pages/experiments/theme-provider-scoping.tsx b/docs/pages/experiments/theme-provider-scoping.tsx
index a6f0158f8dbc91..49869d385f223f 100644
--- a/docs/pages/experiments/theme-provider-scoping.tsx
+++ b/docs/pages/experiments/theme-provider-scoping.tsx
@@ -75,25 +75,25 @@ function useFrame() {
   return React.useContext(FrameContext)!;
 }
 
-let frameCount = 0;
-
 function Frame(props: { children: React.ReactNode; onReady: (frame: FrameValue) => void }) {
   const { children, onReady } = props;
   const ref = React.useRef<HTMLIFrameElement>(null);
   const [frame, setFrame] = React.useState<(FrameValue & { cache: EmotionCache }) | null>(null);
   const [height, setHeight] = React.useState(80);
+  // Emotion keys only allow lowercase letters and hyphens, so the id's other characters become letters.
+  const id = React.useId();
+  const cacheKey = `frame-${id.toLowerCase().replace(/[^a-z]/g, (char) => String.fromCharCode(97 + (char.charCodeAt(0) % 26)))}`;
 
   React.useEffect(() => {
     const iframe = ref.current!;
     let observer: ResizeObserver | undefined;
     const init = () => {
       const doc = iframe.contentDocument!;
-      frameCount += 1;
       const value = {
         document: doc,
         window: iframe.contentWindow!,
         cache: createCache({
-          key: `frame${String.fromCharCode(96 + (frameCount % 26 || 26))}`,
+          key: cacheKey,
           container: doc.head,
         }),
       };
@@ -112,7 +112,7 @@ function Frame(props: { children: React.ReactNode; onReady: (frame: FrameValue)
       iframe.removeEventListener('load', init);
       observer?.disconnect();
     };
-  }, [onReady]);
+  }, [onReady, cacheKey]);
 
   return (
     <React.Fragment>
@@ -306,11 +306,15 @@ const scenarios: Scenario[] = [
     ),
   },
   {
-    title: '3. Root + scoped sibling',
-    description: 'The scoped provider sets all its variables on its child, and has its own mode.',
+    title: '3. Root + scoped siblings',
+    description:
+      'A scoped provider sets all its variables on its child, and has its own mode. With a data attribute selector, the color scheme attribute goes on the child too.',
     code: `<ThemeProvider theme={appTheme}><App /></ThemeProvider>
 <ThemeProvider theme={widgetTheme} scoped>
   <div><Widget /></div>
+</ThemeProvider>
+<ThemeProvider theme={widgetDataTheme} scoped defaultMode="dark">
+  <div><Widget /></div>
 </ThemeProvider>`,
     render: () => (
       <React.Fragment>
@@ -326,43 +330,17 @@ const scenarios: Scenario[] = [
             <Swatch label="widget" />
           </div>
         </ScopedRoot>
-      </React.Fragment>
-    ),
-  },
-  {
-    title: '4. Scoped sibling with a data attribute selector',
-    description: 'The color scheme attribute goes on the child too.',
-    code: `<ThemeProvider theme={widgetDataTheme} scoped defaultMode="dark">
-  <div><Widget /></div>
-</ThemeProvider>`,
-    render: () => (
-      <ScopedRoot theme={widgetDataTheme} defaultMode="dark">
-        <div data-inspect="widget child">
-          <Swatch label="widget" />
-        </div>
-      </ScopedRoot>
-    ),
-  },
-  {
-    title: '5. Nested, same variables',
-    description: 'Only component defaults change: the child is left untouched.',
-    code: `<ThemeProvider theme={appTheme}>
-  <ThemeProvider theme={sameVarsTheme}>
-    <div><Button /></div>
-  </ThemeProvider>
-</ThemeProvider>`,
-    render: () => (
-      <Root theme={appTheme}>
-        <ThemeProvider theme={sameVarsTheme}>
-          <div data-inspect="nested child">
-            <Swatch label="nested" />
+        <ScopedRoot theme={widgetDataTheme} defaultMode="dark">
+          <div data-inspect="data selector widget child">
+            <ModeToggle label="widget mode" />
+            <Swatch label="widget" />
           </div>
-        </ThemeProvider>
-      </Root>
+        </ScopedRoot>
+      </React.Fragment>
     ),
   },
   {
-    title: '6. Nested, different variables',
+    title: '4. Nested, different variables',
     description:
       'The child gets a class that only sets the variables that differ. It follows the outer mode.',
     code: `<ThemeProvider theme={appTheme}>
@@ -386,7 +364,7 @@ const scenarios: Scenario[] = [
     ),
   },
   {
-    title: '7. Nested, children that are not a single element',
+    title: '5. Nested, children that are not a single element',
     description:
       'Several children, a Fragment, text and an array: the rule is generated, but no element gets the class, and an error is logged in development.',
     code: `<ThemeProvider theme={promoTheme}><Button /><Button /></ThemeProvider>
@@ -413,7 +391,7 @@ const scenarios: Scenario[] = [
     ),
   },
   {
-    title: '8. Nested, custom component child',
+    title: '6. Nested, custom component child',
     description:
       'A component that renders the className it receives gets the theme. One that drops it silently keeps the outer theme.',
     code: `<ThemeProvider theme={promoTheme}>
@@ -440,7 +418,7 @@ const scenarios: Scenario[] = [
     ),
   },
   {
-    title: '9. Directly nested providers and a function theme',
+    title: '7. Directly nested providers and a function theme',
     description:
       'A provider whose child is another provider passes its class on: the middle theme (primary) and the inner one (secondary) both apply.',
     code: `<ThemeProvider theme={promoTheme}>
@@ -478,7 +456,7 @@ const scenarios: Scenario[] = [
     ),
   },
   {
-    title: '10. Portals',
+    title: '8. Portals',
     description:
       'Dialog, Menu and Tooltip apply the scope to their own root, in a nested provider and in a scoped sibling. useThemeScope() does it for other portals.',
     code: `<ThemeProvider theme={appTheme}>
@@ -508,7 +486,7 @@ const scenarios: Scenario[] = [
     ),
   },
   {
-    title: '11. Forced single-scheme nested section',
+    title: '9. Forced single-scheme nested section',
     description: 'A nested theme with only a dark scheme stays dark whatever the outer mode is.',
     code: `<ThemeProvider theme={appTheme}>
   <ThemeProvider theme={forcedDarkTheme}>
@@ -529,9 +507,9 @@ const scenarios: Scenario[] = [
     ),
   },
   {
-    title: '12. Switching between same and different variables',
+    title: '10. Nested, same variables, then different ones',
     description:
-      'Click the counter, then switch the nested theme: the count is kept, so nothing remounts.',
+      'With sameVarsTheme (only component defaults change), the child is left untouched. Click the counter, then switch to promoTheme: the child gets the class and keeps its count, so nothing remounts.',
     code: `<ThemeProvider theme={appTheme}>
   <ThemeProvider theme={different ? promoTheme : sameVarsTheme}>
     <div><Counter /></div>
@@ -571,8 +549,8 @@ function inspect(doc: Document) {
   const view = doc.defaultView!;
   const values = (element: Element) => {
     const style = view.getComputedStyle(element);
-    const primary = style.getPropertyValue('--mui-palette-primary-main').trim() || '—';
-    return `primary ${primary}, color-scheme ${style.colorScheme}`;
+    const read = (name: string) => style.getPropertyValue(name).trim() || '—';
+    return `primary ${read('--mui-palette-primary-main')}, secondary ${read('--mui-palette-secondary-main')}, color-scheme ${style.colorScheme}`;
   };
   const scope = (element: Element) => {
     const classes = Array.from(element.classList)
@@ -692,40 +670,7 @@ function ScenarioCard({ scenario }: { scenario: Scenario }) {
   );
 }
 
-// Captures the MUI warnings and errors of the whole page, since the scenarios share one JS context.
-// It patches the console when the module loads, so it also catches what the first render logs.
-const consoleMessages: string[] = [];
-const consoleListeners = new Set<() => void>();
-if (typeof window !== 'undefined') {
-  (['warn', 'error'] as const).forEach((level) => {
-    // eslint-disable-next-line no-console
-    const original = console[level];
-    // eslint-disable-next-line no-console
-    console[level] = (...args: unknown[]) => {
-      const text = `${level}: ${String(args[0])}`;
-      if (String(args[0]).startsWith('MUI:') && !consoleMessages.includes(text)) {
-        consoleMessages.push(text);
-        consoleListeners.forEach((listener) => listener());
-      }
-      original(...args);
-    };
-  });
-}
-
-function useConsoleMessages() {
-  React.useSyncExternalStore(
-    (listener) => {
-      consoleListeners.add(listener);
-      return () => consoleListeners.delete(listener);
-    },
-    () => consoleMessages.length,
-    () => 0,
-  );
-  return consoleMessages;
-}
-
 export default function ThemeProviderScoping() {
-  const messages = useConsoleMessages();
   return (
     <React.Fragment>
       <Head title="ThemeProvider scoping playground" description="" />
@@ -735,19 +680,10 @@ export default function ThemeProviderScoping() {
         </Typography>
         <Typography variant="body2" sx={{ mb: 2 }}>
           Temporary page for #49581. Each scenario renders in its own iframe. The right column shows
-          what ended up there: the scope classes and attributes, the computed primary color and
-          color scheme, and the scoped CSS rules (palette and color scheme declarations only). The
-          scenarios share one JS context, so the root provider warning shows up even though each
-          iframe has its own <code>:root</code>.
+          what ended up there: the scope classes and attributes, the computed primary and secondary
+          colors and color scheme, and the scoped CSS rules (palette and color scheme declarations
+          only). Open the browser console for the development warnings and errors.
         </Typography>
-        <Box
-          component="pre"
-          sx={{ p: 1, fontSize: 12, bgcolor: 'grey.100', borderRadius: 1, whiteSpace: 'pre-wrap' }}
-        >
-          {messages.length
-            ? `MUI console messages (whole page):\n${messages.join('\n\n')}`
-            : 'No MUI console messages yet.'}
-        </Box>
         <Stack spacing={3} sx={{ mt: 2 }}>
           {scenarios.map((scenario) => (
             <ScenarioCard key={scenario.title} scenario={scenario} />

From 0a054eeb3c1e35ab96fa00ebfce3358cfd8bcc53 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Wed, 28 Oct 2026 13:06:29 +0100
Subject: [PATCH 20/20] [material-ui][docs] Move the scoped ThemeProvider tests
 and document the SSR limit

- Move the tests into ThemeProvider.test.tsx, next to the other ThemeProvider tests, grouped by nested and scoped providers.
- Add a browser test for a nested provider following an outer data attribute selector.
- Document that `InitColorSchemeScript` doesn't apply to a scoped provider, so it shows its default color scheme until hydration with `defaultMode="system"`.
---
 .../css-theme-variables/configuration.md      |   2 +
 .../src/styles/ThemeProvider.test.tsx         | 421 +++++++++++++++++-
 .../src/styles/ThemeProviderScoped.test.tsx   | 380 ----------------
 3 files changed, 421 insertions(+), 382 deletions(-)
 delete mode 100644 packages/mui-material/src/styles/ThemeProviderScoped.test.tsx

diff --git a/docs/data/material/customization/css-theme-variables/configuration.md b/docs/data/material/customization/css-theme-variables/configuration.md
index fb9ff1a2f5d49a..b94dd7c3f5bd02 100644
--- a/docs/data/material/customization/css-theme-variables/configuration.md
+++ b/docs/data/material/customization/css-theme-variables/configuration.md
@@ -357,6 +357,8 @@ A scoped provider sets all of its variables on its child element, and has its ow
 If the theme's `colorSchemeSelector` uses a data attribute, the child also needs to render the `data-*` props it receives.
 Its mode isn't stored, so it doesn't overwrite the mode of the page's provider.
 To remember it across visits, pass your own `modeStorageKey` and `colorSchemeStorageKey`.
+`InitColorSchemeScript` only applies to the page's provider, so with server-side rendering and `defaultMode="system"`, a scoped provider shows its default color scheme until the page hydrates.
+To avoid that, give it a fixed `defaultMode`, or render it on the client only.
 
 :::info
 A CSS variable that you override on `:root` doesn't reach the elements under a scoped provider that sets it, because the closest declaration wins.
diff --git a/packages/mui-material/src/styles/ThemeProvider.test.tsx b/packages/mui-material/src/styles/ThemeProvider.test.tsx
index 6276a86c260a38..2b28ad70bc5fd6 100644
--- a/packages/mui-material/src/styles/ThemeProvider.test.tsx
+++ b/packages/mui-material/src/styles/ThemeProvider.test.tsx
@@ -1,7 +1,16 @@
 import { describe, beforeEach, afterEach, it, expect } from 'vitest';
-import { createRenderer, renderHook, screen } from '@mui/internal-test-utils';
-import { ThemeProvider, createTheme, useColorScheme, useTheme } from '@mui/material/styles';
+import * as React from 'react';
+import { createRenderer, renderHook, screen, fireEvent, isJsdom } from '@mui/internal-test-utils';
+import {
+  ThemeProvider,
+  createTheme,
+  useColorScheme,
+  useTheme,
+  useThemeScope,
+} from '@mui/material/styles';
 import Button from '@mui/material/Button';
+import Dialog from '@mui/material/Dialog';
+import Popper from '@mui/material/Popper';
 
 describe('ThemeProvider', () => {
   const { render } = createRenderer();
@@ -187,4 +196,412 @@ describe('ThemeProvider', () => {
       expect(theme.vars).to.equal(null);
     });
   });
+  describe('scoped CSS theme variables', () => {
+    const blueTheme = createTheme({
+      cssVariables: true,
+      palette: { primary: { main: '#0000ff' } },
+    });
+    const redTheme = createTheme({ cssVariables: true, palette: { primary: { main: '#ff0000' } } });
+
+    function getVar(element: Element, name: string) {
+      return getComputedStyle(element).getPropertyValue(name).trim();
+    }
+
+    afterEach(() => {
+      document.documentElement.classList.remove('light', 'dark');
+      document.documentElement.removeAttribute('data-light');
+      document.documentElement.removeAttribute('data-dark');
+    });
+
+    describe('nested provider', () => {
+      it('adds the scope class to the child when the variables differ', () => {
+        render(
+          <ThemeProvider theme={blueTheme}>
+            <div data-testid="outer">
+              <ThemeProvider theme={redTheme}>
+                <div data-testid="inner" className="inner" />
+              </ThemeProvider>
+            </div>
+          </ThemeProvider>,
+        );
+        const inner = screen.getByTestId('inner');
+        expect(inner.parentElement).to.equal(screen.getByTestId('outer'));
+        expect(inner.className).to.match(/^inner mui-theme-[a-z0-9]+$/);
+      });
+
+      it('leaves any children untouched when the theme is the same', () => {
+        render(
+          <ThemeProvider theme={blueTheme}>
+            <div data-testid="outer">
+              <ThemeProvider theme={blueTheme}>
+                <div data-testid="inner" />
+              </ThemeProvider>
+            </div>
+          </ThemeProvider>,
+        );
+        expect(screen.getByTestId('inner').className).to.equal('');
+      });
+
+      it('leaves the child untouched when the theme only changes component defaults', () => {
+        const theme = createTheme({
+          cssVariables: true,
+          palette: { primary: { main: '#0000ff' } },
+          components: { MuiButton: { defaultProps: { disableRipple: true } } },
+        });
+        render(
+          <ThemeProvider theme={blueTheme}>
+            <div data-testid="outer">
+              <ThemeProvider theme={theme}>
+                <div data-testid="inner" />
+              </ThemeProvider>
+            </div>
+          </ThemeProvider>,
+        );
+        expect(screen.getByTestId('inner').className).to.equal('');
+      });
+
+      it('keeps the state of the child when the variables start to differ', () => {
+        function Counter() {
+          const [count, setCount] = React.useState(0);
+          return (
+            <button type="button" data-testid="counter" onClick={() => setCount(count + 1)}>
+              {count}
+            </button>
+          );
+        }
+        const { setProps } = render(
+          <ThemeProvider theme={blueTheme}>
+            <ThemeProvider theme={blueTheme}>
+              <Counter />
+            </ThemeProvider>
+          </ThemeProvider>,
+        );
+        fireEvent.click(screen.getByTestId('counter'));
+        setProps({
+          children: (
+            <ThemeProvider theme={redTheme}>
+              <Counter />
+            </ThemeProvider>
+          ),
+        });
+        expect(screen.getByTestId('counter').textContent).to.equal('1');
+      });
+
+      it('logs an error and applies nothing when the children are not a single element', () => {
+        expect(() =>
+          render(
+            <ThemeProvider theme={blueTheme}>
+              <ThemeProvider theme={redTheme}>
+                <div data-testid="first" />
+                <div />
+              </ThemeProvider>
+            </ThemeProvider>,
+          ),
+        ).toErrorDev("MUI: The CSS theme variables of this ThemeProvider can't be applied");
+        expect(screen.getByTestId('first').className).to.equal('');
+      });
+
+      it('logs an error when the child is a Fragment', () => {
+        expect(() =>
+          render(
+            <ThemeProvider theme={blueTheme}>
+              <ThemeProvider theme={redTheme}>
+                <React.Fragment>
+                  <div />
+                  <div />
+                </React.Fragment>
+              </ThemeProvider>
+            </ThemeProvider>,
+          ),
+        ).toErrorDev("MUI: The CSS theme variables of this ThemeProvider can't be applied");
+      });
+
+      it('does not log an error when there are no children', () => {
+        render(
+          <ThemeProvider theme={blueTheme}>
+            <ThemeProvider theme={redTheme}>{false}</ThemeProvider>
+            <ThemeProvider theme={redTheme}>{null}</ThemeProvider>
+          </ThemeProvider>,
+        );
+      });
+
+      it.skipIf(isJsdom())('applies the inner variables only to the children', () => {
+        render(
+          <ThemeProvider theme={blueTheme}>
+            <Button variant="contained" data-testid="outer">
+              Outer
+            </Button>
+            <ThemeProvider theme={redTheme}>
+              <Button variant="contained" data-testid="inner">
+                Inner
+              </Button>
+            </ThemeProvider>
+          </ThemeProvider>,
+        );
+        expect(getVar(screen.getByTestId('outer'), '--mui-palette-primary-main')).to.equal(
+          '#0000ff',
+        );
+        expect(getVar(screen.getByTestId('inner'), '--mui-palette-primary-main')).to.equal(
+          '#ff0000',
+        );
+        expect(getComputedStyle(screen.getByTestId('inner')).backgroundColor).to.equal(
+          'rgb(255, 0, 0)',
+        );
+      });
+
+      it.skipIf(isJsdom())('applies the inner variables to portaled dialogs and poppers', () => {
+        function Anchored() {
+          const [anchorEl, setAnchorEl] = React.useState<HTMLElement | null>(null);
+          return (
+            <React.Fragment>
+              <div ref={setAnchorEl} />
+              <Popper open={!!anchorEl} anchorEl={anchorEl} data-testid="popper">
+                popper
+              </Popper>
+            </React.Fragment>
+          );
+        }
+        render(
+          <ThemeProvider theme={blueTheme}>
+            <ThemeProvider theme={redTheme}>
+              <div>
+                <Dialog open>
+                  <div data-testid="dialog-content" />
+                </Dialog>
+                <Anchored />
+              </div>
+            </ThemeProvider>
+          </ThemeProvider>,
+        );
+        expect(getVar(screen.getByTestId('dialog-content'), '--mui-palette-primary-main')).to.equal(
+          '#ff0000',
+        );
+        expect(getVar(screen.getByTestId('popper'), '--mui-palette-primary-main')).to.equal(
+          '#ff0000',
+        );
+      });
+
+      it.skipIf(isJsdom())('follows the outer color scheme', () => {
+        const outer = createTheme({
+          cssVariables: { colorSchemeSelector: 'class' },
+          colorSchemes: { light: true, dark: true },
+        });
+        const inner = createTheme({
+          cssVariables: { colorSchemeSelector: 'class' },
+          colorSchemes: {
+            light: { palette: { primary: { main: '#ff0000' } } },
+            dark: { palette: { primary: { main: '#00ff00' } } },
+          },
+        });
+        render(
+          <ThemeProvider theme={outer} defaultMode="dark" storageManager={null}>
+            <ThemeProvider theme={inner}>
+              <div data-testid="inner" />
+            </ThemeProvider>
+          </ThemeProvider>,
+        );
+        expect(document.documentElement.classList.contains('dark')).to.equal(true);
+        expect(getVar(screen.getByTestId('inner'), '--mui-palette-primary-main')).to.equal(
+          '#00ff00',
+        );
+      });
+
+      it.skipIf(isJsdom())('follows the outer color scheme with a data attribute selector', () => {
+        const outer = createTheme({
+          cssVariables: { colorSchemeSelector: 'data' },
+          colorSchemes: { light: true, dark: true },
+        });
+        const inner = createTheme({
+          cssVariables: { colorSchemeSelector: 'data' },
+          colorSchemes: {
+            light: { palette: { primary: { main: '#ff0000' } } },
+            dark: { palette: { primary: { main: '#00ff00' } } },
+          },
+        });
+        render(
+          <ThemeProvider theme={outer} defaultMode="dark" storageManager={null}>
+            <ThemeProvider theme={inner}>
+              <div data-testid="inner" />
+            </ThemeProvider>
+          </ThemeProvider>,
+        );
+        expect(document.documentElement).to.have.attribute('data-dark', '');
+        expect(getVar(screen.getByTestId('inner'), '--mui-palette-primary-main')).to.equal(
+          '#00ff00',
+        );
+      });
+
+      it.skipIf(isJsdom())('passes the scope of a provider whose child is another provider', () => {
+        const greenSecondaryTheme = createTheme({
+          cssVariables: true,
+          palette: { primary: { main: '#ff0000' }, secondary: { main: '#00ff00' } },
+        });
+        render(
+          <ThemeProvider theme={blueTheme}>
+            <ThemeProvider theme={redTheme}>
+              <ThemeProvider theme={greenSecondaryTheme}>
+                <div data-testid="inner" />
+              </ThemeProvider>
+            </ThemeProvider>
+          </ThemeProvider>,
+        );
+        expect(getVar(screen.getByTestId('inner'), '--mui-palette-primary-main')).to.equal(
+          '#ff0000',
+        );
+        expect(getVar(screen.getByTestId('inner'), '--mui-palette-secondary-main')).to.equal(
+          '#00ff00',
+        );
+      });
+
+      it('passes the scope through a provider with a function theme', () => {
+        render(
+          <ThemeProvider theme={blueTheme}>
+            <ThemeProvider theme={redTheme}>
+              <ThemeProvider theme={(outer: object) => ({ ...outer })}>
+                <div data-testid="inner" />
+              </ThemeProvider>
+            </ThemeProvider>
+          </ThemeProvider>,
+        );
+        expect(screen.getByTestId('inner').className).to.match(/^mui-theme-[a-z0-9]+$/);
+      });
+
+      it('passes the color scheme attribute of a scoped provider through a function theme', () => {
+        const theme = createTheme({
+          cssVariables: { colorSchemeSelector: 'data' },
+          colorSchemes: { light: true, dark: true },
+        });
+        render(
+          <ThemeProvider theme={theme} scoped defaultMode="dark">
+            <ThemeProvider theme={(outer: object) => ({ ...outer })}>
+              <div data-testid="widget" />
+            </ThemeProvider>
+          </ThemeProvider>,
+        );
+        expect(screen.getByTestId('widget')).to.have.attribute('data-dark', '');
+        expect(screen.getByTestId('widget').className).to.match(/^mui-theme-[a-z0-9]+$/);
+      });
+    });
+
+    describe('scoped prop', () => {
+      it.skipIf(isJsdom())('keeps a sibling provider off :root', () => {
+        const darkTheme = createTheme({
+          cssVariables: true,
+          palette: { mode: 'dark', primary: { main: '#ff0000' } },
+        });
+        render(
+          <React.Fragment>
+            <ThemeProvider theme={blueTheme}>
+              <div data-testid="app" />
+            </ThemeProvider>
+            <ThemeProvider theme={darkTheme} scoped>
+              <div data-testid="widget" />
+            </ThemeProvider>
+          </React.Fragment>,
+        );
+        expect(getVar(document.documentElement, '--mui-palette-primary-main')).to.equal('#0000ff');
+        expect(getComputedStyle(document.documentElement).colorScheme).not.to.equal('dark');
+        expect(getVar(screen.getByTestId('app'), '--mui-palette-primary-main')).to.equal('#0000ff');
+        expect(getVar(screen.getByTestId('widget'), '--mui-palette-primary-main')).to.equal(
+          '#ff0000',
+        );
+        expect(getComputedStyle(screen.getByTestId('widget')).colorScheme).to.equal('dark');
+      });
+
+      it('adds the color scheme attribute to the child', () => {
+        const theme = createTheme({
+          cssVariables: { colorSchemeSelector: 'data' },
+          colorSchemes: { light: true, dark: true },
+        });
+        render(
+          <ThemeProvider theme={theme} scoped defaultMode="dark">
+            <div data-testid="widget" />
+          </ThemeProvider>,
+        );
+        expect(screen.getByTestId('widget')).to.have.attribute('data-dark', '');
+        expect(document.documentElement).not.to.have.attribute('data-dark');
+      });
+
+      it('only uses the storage for a scoped provider with storage keys', () => {
+        const theme = createTheme({
+          cssVariables: { colorSchemeSelector: 'class' },
+          colorSchemes: { light: true, dark: true },
+        });
+        const readKeys: string[] = [];
+        const storageWindow = {
+          localStorage: {
+            getItem: (key: string) => {
+              readKeys.push(key);
+              return null;
+            },
+            setItem: () => {},
+          },
+          addEventListener: () => {},
+          removeEventListener: () => {},
+        } as unknown as Window;
+        render(
+          <React.Fragment>
+            <ThemeProvider theme={theme} scoped storageWindow={storageWindow}>
+              <div />
+            </ThemeProvider>
+            <ThemeProvider
+              theme={theme}
+              scoped
+              modeStorageKey="widget-mode"
+              colorSchemeStorageKey="widget-color-scheme"
+              storageWindow={storageWindow}
+            >
+              <div />
+            </ThemeProvider>
+          </React.Fragment>,
+        );
+        expect(readKeys.length).to.be.greaterThan(0);
+        expect(readKeys.every((key) => key.startsWith('widget-'))).to.equal(true);
+      });
+
+      it('warns when two providers with different themes write to :root', () => {
+        expect(() =>
+          render(
+            <React.Fragment>
+              <ThemeProvider theme={blueTheme}>
+                <div />
+              </ThemeProvider>
+              <ThemeProvider theme={redTheme}>
+                <div />
+              </ThemeProvider>
+            </React.Fragment>,
+          ),
+        ).toWarnDev('MUI: Several ThemeProviders with different themes write');
+      });
+    });
+
+    it('leaves the children of the top-level provider untouched', () => {
+      render(
+        <ThemeProvider theme={redTheme}>
+          <div data-testid="first" />
+          <div />
+        </ThemeProvider>,
+      );
+      expect(screen.getByTestId('first').className).to.equal('');
+    });
+
+    it('exposes the scope class to elements that are portaled by other libraries', () => {
+      function Scope() {
+        const props = useThemeScope();
+        return <div data-testid="scope" {...props} />;
+      }
+      render(
+        <ThemeProvider theme={blueTheme}>
+          <ThemeProvider theme={redTheme}>
+            <div>
+              <Scope />
+            </div>
+          </ThemeProvider>
+        </ThemeProvider>,
+      );
+      expect(screen.getByTestId('scope').className).to.equal(
+        screen.getByTestId('scope').parentElement!.className,
+      );
+    });
+  });
 });
diff --git a/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx b/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
deleted file mode 100644
index 5a02c8ba9b19a4..00000000000000
--- a/packages/mui-material/src/styles/ThemeProviderScoped.test.tsx
+++ /dev/null
@@ -1,380 +0,0 @@
-import { describe, it, expect, afterEach } from 'vitest';
-import * as React from 'react';
-import { createRenderer, screen, isJsdom, fireEvent } from '@mui/internal-test-utils';
-import Button from '@mui/material/Button';
-import Dialog from '@mui/material/Dialog';
-import Popper from '@mui/material/Popper';
-import { ThemeProvider, createTheme, useThemeScope } from '@mui/material/styles';
-
-function getVar(element: Element, name: string) {
-  return getComputedStyle(element).getPropertyValue(name).trim();
-}
-
-const blueTheme = createTheme({ cssVariables: true, palette: { primary: { main: '#0000ff' } } });
-const redTheme = createTheme({ cssVariables: true, palette: { primary: { main: '#ff0000' } } });
-
-describe('ThemeProvider with scoped CSS theme variables', () => {
-  const { render } = createRenderer();
-
-  afterEach(() => {
-    document.documentElement.classList.remove('light', 'dark');
-  });
-
-  describe('nested', () => {
-    it('adds the scope class to the child when the variables differ', () => {
-      render(
-        <ThemeProvider theme={blueTheme}>
-          <div data-testid="outer">
-            <ThemeProvider theme={redTheme}>
-              <div data-testid="inner" className="inner" />
-            </ThemeProvider>
-          </div>
-        </ThemeProvider>,
-      );
-      const inner = screen.getByTestId('inner');
-      expect(inner.parentElement).to.equal(screen.getByTestId('outer'));
-      expect(inner.className).to.match(/^inner mui-theme-[a-z0-9]+$/);
-    });
-
-    it('keeps the state of the child when the variables start to differ', () => {
-      function Counter() {
-        const [count, setCount] = React.useState(0);
-        return (
-          <button type="button" data-testid="counter" onClick={() => setCount(count + 1)}>
-            {count}
-          </button>
-        );
-      }
-      const { setProps } = render(
-        <ThemeProvider theme={blueTheme}>
-          <ThemeProvider theme={blueTheme}>
-            <Counter />
-          </ThemeProvider>
-        </ThemeProvider>,
-      );
-      fireEvent.click(screen.getByTestId('counter'));
-      setProps({
-        children: (
-          <ThemeProvider theme={redTheme}>
-            <Counter />
-          </ThemeProvider>
-        ),
-      });
-      expect(screen.getByTestId('counter').textContent).to.equal('1');
-    });
-
-    it('logs an error and applies nothing when the children are not a single element', () => {
-      expect(() =>
-        render(
-          <ThemeProvider theme={blueTheme}>
-            <ThemeProvider theme={redTheme}>
-              <div data-testid="first" />
-              <div />
-            </ThemeProvider>
-          </ThemeProvider>,
-        ),
-      ).toErrorDev("MUI: The CSS theme variables of this ThemeProvider can't be applied");
-      expect(screen.getByTestId('first').className).to.equal('');
-    });
-
-    it('does not log an error when there are no children', () => {
-      render(
-        <ThemeProvider theme={blueTheme}>
-          <ThemeProvider theme={redTheme}>{false}</ThemeProvider>
-          <ThemeProvider theme={redTheme}>{null}</ThemeProvider>
-        </ThemeProvider>,
-      );
-    });
-
-    it.skipIf(isJsdom())('passes the scope of a provider whose child is another provider', () => {
-      const greenSecondaryTheme = createTheme({
-        cssVariables: true,
-        palette: { primary: { main: '#ff0000' }, secondary: { main: '#00ff00' } },
-      });
-      render(
-        <ThemeProvider theme={blueTheme}>
-          <ThemeProvider theme={redTheme}>
-            <ThemeProvider theme={greenSecondaryTheme}>
-              <div data-testid="inner" />
-            </ThemeProvider>
-          </ThemeProvider>
-        </ThemeProvider>,
-      );
-      expect(getVar(screen.getByTestId('inner'), '--mui-palette-primary-main')).to.equal('#ff0000');
-      expect(getVar(screen.getByTestId('inner'), '--mui-palette-secondary-main')).to.equal(
-        '#00ff00',
-      );
-    });
-
-    it('passes the scope through a provider with a function theme', () => {
-      render(
-        <ThemeProvider theme={blueTheme}>
-          <ThemeProvider theme={redTheme}>
-            <ThemeProvider theme={(outer: object) => ({ ...outer })}>
-              <div data-testid="inner" />
-            </ThemeProvider>
-          </ThemeProvider>
-        </ThemeProvider>,
-      );
-      expect(screen.getByTestId('inner').className).to.match(/^mui-theme-[a-z0-9]+$/);
-    });
-
-    it('passes the color scheme attribute of a scoped provider through a function theme', () => {
-      const theme = createTheme({
-        cssVariables: { colorSchemeSelector: 'data' },
-        colorSchemes: { light: true, dark: true },
-      });
-      render(
-        <ThemeProvider theme={theme} scoped defaultMode="dark">
-          <ThemeProvider theme={(outer: object) => ({ ...outer })}>
-            <div data-testid="widget" />
-          </ThemeProvider>
-        </ThemeProvider>,
-      );
-      expect(screen.getByTestId('widget')).to.have.attribute('data-dark', '');
-      expect(screen.getByTestId('widget').className).to.match(/^mui-theme-[a-z0-9]+$/);
-    });
-
-    it('logs an error when the child is a Fragment', () => {
-      expect(() =>
-        render(
-          <ThemeProvider theme={blueTheme}>
-            <ThemeProvider theme={redTheme}>
-              <React.Fragment>
-                <div />
-                <div />
-              </React.Fragment>
-            </ThemeProvider>
-          </ThemeProvider>,
-        ),
-      ).toErrorDev("MUI: The CSS theme variables of this ThemeProvider can't be applied");
-    });
-
-    it('leaves any children untouched when the theme is the same', () => {
-      render(
-        <ThemeProvider theme={blueTheme}>
-          <div data-testid="outer">
-            <ThemeProvider theme={blueTheme}>
-              <div data-testid="inner" />
-            </ThemeProvider>
-          </div>
-        </ThemeProvider>,
-      );
-      expect(screen.getByTestId('inner').className).to.equal('');
-    });
-
-    it('leaves the child untouched when the theme only changes component defaults', () => {
-      const theme = createTheme({
-        cssVariables: true,
-        palette: { primary: { main: '#0000ff' } },
-        components: { MuiButton: { defaultProps: { disableRipple: true } } },
-      });
-      render(
-        <ThemeProvider theme={blueTheme}>
-          <div data-testid="outer">
-            <ThemeProvider theme={theme}>
-              <div data-testid="inner" />
-            </ThemeProvider>
-          </div>
-        </ThemeProvider>,
-      );
-      expect(screen.getByTestId('inner').className).to.equal('');
-    });
-
-    it.skipIf(isJsdom())('applies the inner variables only to the children', () => {
-      render(
-        <ThemeProvider theme={blueTheme}>
-          <Button variant="contained" data-testid="outer">
-            Outer
-          </Button>
-          <ThemeProvider theme={redTheme}>
-            <Button variant="contained" data-testid="inner">
-              Inner
-            </Button>
-          </ThemeProvider>
-        </ThemeProvider>,
-      );
-      expect(getVar(screen.getByTestId('outer'), '--mui-palette-primary-main')).to.equal('#0000ff');
-      expect(getVar(screen.getByTestId('inner'), '--mui-palette-primary-main')).to.equal('#ff0000');
-      expect(getComputedStyle(screen.getByTestId('inner')).backgroundColor).to.equal(
-        'rgb(255, 0, 0)',
-      );
-    });
-
-    it.skipIf(isJsdom())('applies the inner variables to portaled dialogs and poppers', () => {
-      function Anchored() {
-        const [anchorEl, setAnchorEl] = React.useState<HTMLElement | null>(null);
-        return (
-          <React.Fragment>
-            <div ref={setAnchorEl} />
-            <Popper open={!!anchorEl} anchorEl={anchorEl} data-testid="popper">
-              popper
-            </Popper>
-          </React.Fragment>
-        );
-      }
-      render(
-        <ThemeProvider theme={blueTheme}>
-          <ThemeProvider theme={redTheme}>
-            <div>
-              <Dialog open>
-                <div data-testid="dialog-content" />
-              </Dialog>
-              <Anchored />
-            </div>
-          </ThemeProvider>
-        </ThemeProvider>,
-      );
-      expect(getVar(screen.getByTestId('dialog-content'), '--mui-palette-primary-main')).to.equal(
-        '#ff0000',
-      );
-      expect(getVar(screen.getByTestId('popper'), '--mui-palette-primary-main')).to.equal(
-        '#ff0000',
-      );
-    });
-
-    it.skipIf(isJsdom())('follows the outer color scheme', () => {
-      const outer = createTheme({
-        cssVariables: { colorSchemeSelector: 'class' },
-        colorSchemes: { light: true, dark: true },
-      });
-      const inner = createTheme({
-        cssVariables: { colorSchemeSelector: 'class' },
-        colorSchemes: {
-          light: { palette: { primary: { main: '#ff0000' } } },
-          dark: { palette: { primary: { main: '#00ff00' } } },
-        },
-      });
-      render(
-        <ThemeProvider theme={outer} defaultMode="dark" storageManager={null}>
-          <ThemeProvider theme={inner}>
-            <div data-testid="inner" />
-          </ThemeProvider>
-        </ThemeProvider>,
-      );
-      expect(document.documentElement.classList.contains('dark')).to.equal(true);
-      expect(getVar(screen.getByTestId('inner'), '--mui-palette-primary-main')).to.equal('#00ff00');
-    });
-  });
-
-  describe('scoped prop', () => {
-    it.skipIf(isJsdom())('keeps a sibling provider off :root', () => {
-      const darkTheme = createTheme({
-        cssVariables: true,
-        palette: { mode: 'dark', primary: { main: '#ff0000' } },
-      });
-      render(
-        <React.Fragment>
-          <ThemeProvider theme={blueTheme}>
-            <div data-testid="app" />
-          </ThemeProvider>
-          <ThemeProvider theme={darkTheme} scoped>
-            <div data-testid="widget" />
-          </ThemeProvider>
-        </React.Fragment>,
-      );
-      expect(getVar(document.documentElement, '--mui-palette-primary-main')).to.equal('#0000ff');
-      expect(getComputedStyle(document.documentElement).colorScheme).not.to.equal('dark');
-      expect(getVar(screen.getByTestId('app'), '--mui-palette-primary-main')).to.equal('#0000ff');
-      expect(getVar(screen.getByTestId('widget'), '--mui-palette-primary-main')).to.equal(
-        '#ff0000',
-      );
-      expect(getComputedStyle(screen.getByTestId('widget')).colorScheme).to.equal('dark');
-    });
-
-    it('only uses the storage for a scoped provider with storage keys', () => {
-      const theme = createTheme({
-        cssVariables: { colorSchemeSelector: 'class' },
-        colorSchemes: { light: true, dark: true },
-      });
-      const readKeys: string[] = [];
-      const storageWindow = {
-        localStorage: {
-          getItem: (key: string) => {
-            readKeys.push(key);
-            return null;
-          },
-          setItem: () => {},
-        },
-        addEventListener: () => {},
-        removeEventListener: () => {},
-      } as unknown as Window;
-      render(
-        <React.Fragment>
-          <ThemeProvider theme={theme} scoped storageWindow={storageWindow}>
-            <div />
-          </ThemeProvider>
-          <ThemeProvider
-            theme={theme}
-            scoped
-            modeStorageKey="widget-mode"
-            colorSchemeStorageKey="widget-color-scheme"
-            storageWindow={storageWindow}
-          >
-            <div />
-          </ThemeProvider>
-        </React.Fragment>,
-      );
-      expect(readKeys.length).to.be.greaterThan(0);
-      expect(readKeys.every((key) => key.startsWith('widget-'))).to.equal(true);
-    });
-
-    it('adds the color scheme attribute to the child', () => {
-      const theme = createTheme({
-        cssVariables: { colorSchemeSelector: 'data' },
-        colorSchemes: { light: true, dark: true },
-      });
-      render(
-        <ThemeProvider theme={theme} scoped defaultMode="dark">
-          <div data-testid="widget" />
-        </ThemeProvider>,
-      );
-      expect(screen.getByTestId('widget')).to.have.attribute('data-dark', '');
-      expect(document.documentElement).not.to.have.attribute('data-dark');
-    });
-
-    it('warns when two providers with different themes write to :root', () => {
-      expect(() =>
-        render(
-          <React.Fragment>
-            <ThemeProvider theme={blueTheme}>
-              <div />
-            </ThemeProvider>
-            <ThemeProvider theme={redTheme}>
-              <div />
-            </ThemeProvider>
-          </React.Fragment>,
-        ),
-      ).toWarnDev('MUI: Several ThemeProviders with different themes write');
-    });
-  });
-
-  it('leaves the children of the top-level provider untouched', () => {
-    render(
-      <ThemeProvider theme={redTheme}>
-        <div data-testid="first" />
-        <div />
-      </ThemeProvider>,
-    );
-    expect(screen.getByTestId('first').className).to.equal('');
-  });
-
-  it('exposes the scope class to elements that are portaled by other libraries', () => {
-    function Scope() {
-      const props = useThemeScope();
-      return <div data-testid="scope" {...props} />;
-    }
-    render(
-      <ThemeProvider theme={blueTheme}>
-        <ThemeProvider theme={redTheme}>
-          <div>
-            <Scope />
-          </div>
-        </ThemeProvider>
-      </ThemeProvider>,
-    );
-    expect(screen.getByTestId('scope').className).to.equal(
-      screen.getByTestId('scope').parentElement!.className,
-    );
-  });
-});