[docs] Add Shadow DOM guide

docs/data/material/guides/shadow-dom/ShadowDOMDemo.js

@@ -0,0 +1,16 @@
+import * as React from 'react';
+
+export default function ShadowDOMDemo() {
+  return (
+    <iframe
+      title="codesandbox"
+      src="https://codesandbox.io/embed/basicselect-demo-material-ui-forked-rki9k5?hidenavigation=1&fontsize=14&view=preview&hidedevtools=1"
+      style={{
+        width: '100%',
+        height: 350,
+        border: 0,
+      }}
+      sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin hidenavigation"
+    />
+  );
+}

docs/data/material/guides/shadow-dom/ShadowDOMDemo.tsx

@@ -0,0 +1,16 @@
+import * as React from 'react';
+
+export default function ShadowDOMDemo() {
+  return (
+    <iframe
+      title="codesandbox"
+      src="https://codesandbox.io/embed/basicselect-demo-material-ui-forked-rki9k5?hidenavigation=1&fontsize=14&view=preview&hidedevtools=1"
+      style={{
+        width: '100%',
+        height: 350,
+        border: 0,
+      }}
+      sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin hidenavigation"
+    />
+  );
+}

docs/data/material/guides/shadow-dom/ShadowDOMDemo.tsx.preview

@@ -0,0 +1,10 @@
+<iframe
+  title="codesandbox"
+  src="https://codesandbox.io/embed/basicselect-demo-material-ui-forked-rki9k5?hidenavigation=1&fontsize=14&view=preview&hidedevtools=1"
+  style={{
+    width: '100%',
+    height: 350,
+    border: 0,
+  }}
+  sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin hidenavigation"
+/>

docs/data/material/guides/shadow-dom/shadow-dom.md

@@ -0,0 +1,69 @@
+# Shadow DOM
+
+<p class="description">The shadow DOM lets you encapsulate parts of an app to keep them separate from global styles that target the regular DOM tree.</p>
+
+## How to use the shadow DOM with Material UI
+
+### 1. Styles
+
+The shadow DOM is an API that provides a way to attach a hidden separated DOM to an element.
+This is useful when you need to keep the structure, style, and behavior of different components separate from the rest of the code on the page, to prevent conflicts.
+See [the MDN docs on the shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) for more information.
+The following code snippet shows how to apply styles inside of the shadow DOM:
+
+```tsx
+const container = document.querySelector('#root');
+const shadowContainer = container.attachShadow({ mode: 'open' });
+const emotionRoot = document.createElement('style');
+const shadowRootElement = document.createElement('div');
+shadowContainer.appendChild(emotionRoot);
+shadowContainer.appendChild(shadowRootElement);
+
+const cache = createCache({
+  key: 'css',
+  prepend: true,
+  container: emotionRoot,
+});
+
+ReactDOM.createRoot(shadowRootElement).render(
+  <CacheProvider value={cache}>
+    <App />
+  </CacheProvider>,
+);
+```
+
+### 2. Theme
+
+MUI components like `Menu`, `Dialog`, `Popover` and others use [`Portal`](/material-ui/react-portal/) to render a new "subtree" in a container outside of current DOM hierarchy.
+By default, this container is `document.body`.
+
+But since the styles are applied only inside of the Shadow DOM, we need to render portals inside the Shadow DOM container as well:
+
+```tsx
+const theme = createTheme({
+  components: {
+    MuiPopover: {
+      defaultProps: {
+        container: shadowRootElement,
+      },
+    },
+    MuiPopper: {
+      defaultProps: {
+        container: shadowRootElement,
+      },
+    },
+  },
+});
+
+// ...
+
+<ThemeProvider theme={theme}>
+  <App />
+</ThemeProvider>;
+```
+
+## Demo
+
+In the example below you can see that the component outside of the shadow DOM is affected by global styles, while the component inside of the shadow DOM is not:
+
+{{"demo": "ShadowDOMDemo.js", "defaultCodeOpen": false}}

docs/data/material/pages.ts

@@ -208,6 +208,7 @@ const pages = [
       { pathname: '/material-ui/guides/content-security-policy', title: 'Content Security Policy' },
       { pathname: '/material-ui/guides/right-to-left', title: 'Right-to-left' },
       { pathname: '/material-ui/guides/flow' },
+      { pathname: '/material-ui/guides/shadow-dom', title: 'Shadow DOM' },
     ],
   },
   {

docs/pages/material-ui/guides/shadow-dom.js

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import {
+  demos,
+  docs,
+  demoComponents,
+} from 'docs/data/material/guides/shadow-dom/shadow-dom.md?@mui/markdown';
+
+export default function Page() {
+  return <MarkdownDocs demos={demos} docs={docs} demoComponents={demoComponents} />;
+}

docs/translations/translations.json

@@ -324,6 +324,7 @@
     "/material-ui/guides/content-security-policy": "Content Security Policy",
     "/material-ui/guides/right-to-left": "Right-to-left",
     "/material-ui/guides/flow": "Flow",
+    "/material-ui/guides/shadow-dom": "Shadow DOM",
     "/material-ui/experimental-api": "Experimental APIs",
     "/material-ui/experimental-api/classname-generator": "ClassName generator",
     "/material-ui/experimental-api/css-variables": "CSS variables",