[material-ui][docs] Add Material 3 components page (#40350)

docs/data/material/components/badges/badges.md

@@ -74,13 +74,15 @@ You should provide a full description, for instance, with `aria-label`:
 
 ## Experimental APIs
 
-### Material You version
+### Material 3 version
 
 The default Material UI Badge component follows the Material Design 2 specs.
-To get the Material You ([Material Design 3](https://m3.material.io/)) version, use the new experimental `@mui/material-next` package:
+To get the [Material 3](https://m3.material.io/) version, use the new experimental `@mui/material-next` package.
 
 ```js
 import Badge from '@mui/material-next/Badge';
 ```
 
 {{"demo": "BadgeMaterialYouPlayground.js", "hideToolbar": true, "bg": "playground"}}
+
+For more instructions on how to use it, visit the [detailed guide](/material-ui/guides/material-3-components/).

docs/data/material/components/buttons/buttons.md

@@ -199,13 +199,15 @@ To prevent this, ensure that the contents of the Loading Button are nested insid
 
 :::
 
-### Material You version
+### Material 3 version
 
 The default Material UI Button component follows the Material Design 2 specs.
-To get the Material You ([Material Design 3](https://m3.material.io/)) version, use the new experimental `@mui/material-next` package:
+To get the [Material 3](https://m3.material.io/) version, use the new experimental `@mui/material-next` package.
 
 ```js
 import Button from '@mui/material-next/Button';
 ```
 
 {{"demo": "ButtonMaterialYouPlayground.js", "hideToolbar": true, "bg": "playground"}}
+
+For more instructions on how to use it, visit the [detailed guide](/material-ui/guides/material-3-components/).

docs/data/material/components/chips/ChipMaterialYouPlayground.js

@@ -45,12 +45,12 @@ export default function ChipMaterialYouPlayground() {
           <Chip
             {...props}
             label="Clickable chip"
-            onClick={() => alert('Clicked Material You Chip')}
+            onClick={() => alert('Clicked Material 3 Chip')}
           />
           <Chip
             {...props}
             label="Deletable chip"
-            onDelete={() => alert('Deleted Material You Chip')}
+            onDelete={() => alert('Deleted Material 3 Chip')}
           />
         </Box>
       )}

docs/data/material/components/chips/chips.md

@@ -99,17 +99,19 @@ gain depth while clicked or touched.
 
 ## Experimental API
 
-### Material You version
+### Material 3 version
 
 The default Material UI Chip component follows the Material Design 2 specs.
-To get the Material You ([Material Design 3](https://m3.material.io/)) version, use the new experimental `@mui/material-next` package:
+To get the [Material 3](https://m3.material.io/) version, use the new experimental `@mui/material-next` package.
 
 ```js
 import Chip from '@mui/material-next/Chip';
 ```
 
 {{"demo": "ChipMaterialYouPlayground.js", "hideToolbar": true, "bg": "playground"}}
 
+For more instructions on how to use it, visit the [detailed guide](/material-ui/guides/material-3-components/).
+
 ## Accessibility
 
 If the Chip is deletable or clickable then it is a button in tab order. When the Chip is focused (e.g. when tabbing) releasing (`keyup` event) `Backspace` or `Delete` will call the `onDelete` handler while releasing `Escape` will blur the Chip.

docs/data/material/components/dividers/dividers.md

@@ -99,11 +99,13 @@ The Divider component is composed of a root `<hr>`.
 
 ### Material 3 version
 
-The default Material UI Divider component follows the [Material Design 2](https://m2.material.io/) specs.
-To get the Material Design 3 ([Material You](https://m3.material.io/)) version, use the new experimental `@mui/material-next` package:
+The default Material UI Divider component follows the Material Design 2 specs.
+To get the [Material 3](https://m3.material.io/) version, use the new experimental `@mui/material-next` package.
 
 ```js
 import Divider from '@mui/material-next/Divider';
 ```
 
 {{"demo": "DividerMaterialYouPlayground.js", "hideToolbar": true, "bg": "playground"}}
+
+For more instructions on how to use it, visit the [detailed guide](/material-ui/guides/material-3-components/).

docs/data/material/components/progress/progress.md

@@ -153,14 +153,16 @@ You can solve the latter with:
 
 ## Experimental APIs
 
-### Material You version
+### Material 3 version
 
-The default Material UI Progress components follows the Material Design 2 specs.
-To get the Material You ([Material Design 3](https://m3.material.io/)) version, use the new experimental `@mui/material-next` package:
+The default Material UI Progress components follow the Material Design 2 specs.
+To get the [Material 3](https://m3.material.io/) version, use the new experimental `@mui/material-next` package.
 
 ```js
 import CircularProgress from '@mui/material-next/CircularProgress';
 import LinearProgress from '@mui/material-next/LinearProgress';
 ```
 
 {{"demo": "ProgressMaterialYouPlayground.js", "hideToolbar": true, "bg": "playground"}}
+
+For more instructions on how to use it, visit the [detailed guide](/material-ui/guides/material-3-components/).

docs/data/material/components/slider/slider.md

@@ -161,13 +161,15 @@ You can solve the issue with:
 
 ## Experimental APIs
 
-### Material You version
+### Material 3 version
 
 The default Material UI Slider component follows the Material Design 2 specs.
-To get the Material You ([Material Design 3](https://m3.material.io/)) version, use the new experimental `@mui/material-next` package:
+To get the [Material 3](https://m3.material.io/) version, use the new experimental `@mui/material-next` package.
 
 ```js
 import Slider from '@mui/material-next/Slider';
 ```
 
 {{"demo": "SliderMaterialYouPlayground.js", "hideToolbar": true, "bg": "playground"}}
+
+For more instructions on how to use it, visit the [detailed guide](/material-ui/guides/material-3-components/).

docs/data/material/guides/material-3-components/MD3AndV5Usage.js

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import MD2Button from '@mui/material/Button';
+import { ThemeProvider, createTheme } from '@mui/material/styles';
+import MD3Button from '@mui/material-next/Button';
+import { CssVarsProvider, extendTheme } from '@mui/material-next/styles';
+import { Stack } from '@mui/system';
+
+const md2Theme = createTheme();
+const md3Theme = extendTheme();
+
+export default function MD3AndV5Usage() {
+  return (
+    <ThemeProvider theme={md2Theme}>
+      <Stack spacing={2} direction="row">
+        <MD2Button variant="contained">MD2 Button</MD2Button>
+        <CssVarsProvider theme={md3Theme}>
+          <MD3Button variant="filled">MD3 Button</MD3Button>
+        </CssVarsProvider>
+      </Stack>
+    </ThemeProvider>
+  );
+}

docs/data/material/guides/material-3-components/MD3AndV5Usage.tsx

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import MD2Button from '@mui/material/Button';
+import { ThemeProvider, createTheme } from '@mui/material/styles';
+import MD3Button from '@mui/material-next/Button';
+import { CssVarsProvider, extendTheme } from '@mui/material-next/styles';
+import { Stack } from '@mui/system';
+
+const md2Theme = createTheme();
+const md3Theme = extendTheme();
+
+export default function MD3AndV5Usage() {
+  return (
+    <ThemeProvider theme={md2Theme}>
+      <Stack spacing={2} direction="row">
+        <MD2Button variant="contained">MD2 Button</MD2Button>
+        <CssVarsProvider theme={md3Theme}>
+          <MD3Button variant="filled">MD3 Button</MD3Button>
+        </CssVarsProvider>
+      </Stack>
+    </ThemeProvider>
+  );
+}

docs/data/material/guides/material-3-components/MD3AndV5Usage.tsx.preview

@@ -0,0 +1,8 @@
+<ThemeProvider theme={md2Theme}>
+  <Stack spacing={2} direction="row">
+    <MD2Button variant="contained">MD2 Button</MD2Button>
+    <CssVarsProvider theme={md3Theme}>
+      <MD3Button variant="filled">MD3 Button</MD3Button>
+    </CssVarsProvider>
+  </Stack>
+</ThemeProvider>

docs/data/material/guides/material-3-components/MD3ButtonUsage.js

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import Button from '@mui/material-next/Button';
+import { CssVarsProvider } from '@mui/material-next/styles';
+
+export default function MD3ButtonUsage() {
+  return (
+    <CssVarsProvider>
+      <Button variant="filled">Button</Button>
+    </CssVarsProvider>
+  );
+}

docs/data/material/guides/material-3-components/MD3ButtonUsage.tsx

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import Button from '@mui/material-next/Button';
+import { CssVarsProvider } from '@mui/material-next/styles';
+
+export default function MD3ButtonUsage() {
+  return (
+    <CssVarsProvider>
+      <Button variant="filled">Button</Button>
+    </CssVarsProvider>
+  );
+}

docs/data/material/guides/material-3-components/MD3ButtonUsage.tsx.preview

@@ -0,0 +1,3 @@
+<CssVarsProvider>
+  <Button variant="filled">Button</Button>
+</CssVarsProvider>

docs/data/material/guides/material-3-components/MD3Theming.js

@@ -0,0 +1,38 @@
+import * as React from 'react';
+import Button from '@mui/material-next/Button';
+import { extendTheme, CssVarsProvider } from '@mui/material-next/styles';
+
+const customTheme = extendTheme({
+  ref: {
+    palette: {
+      primary: {
+        0: '#000000',
+        10: '#002020',
+        20: '#003738',
+        30: '#004F51',
+        40: '#00696B',
+        50: '#008587',
+        60: '#00A1A3',
+        70: '#00BEC1',
+        80: '#2DDBDE',
+        90: '#8FF3F4',
+        95: '#B2FEFF',
+        99: '#F1FFFF',
+        100: '#FFFFFF',
+      },
+    },
+  },
+  // cssVarPrefix is only required if multiple themes coexist
+  // on the same page like on this guide
+  cssVarPrefix: 'turquoise-md3',
+});
+
+export default function MD3Theming() {
+  return (
+    <CssVarsProvider theme={customTheme}>
+      <Button color="primary" variant="filled">
+        Button
+      </Button>
+    </CssVarsProvider>
+  );
+}

docs/data/material/guides/material-3-components/MD3Theming.tsx

@@ -0,0 +1,38 @@
+import * as React from 'react';
+import Button from '@mui/material-next/Button';
+import { extendTheme, CssVarsProvider } from '@mui/material-next/styles';
+
+const customTheme = extendTheme({
+  ref: {
+    palette: {
+      primary: {
+        0: '#000000',
+        10: '#002020',
+        20: '#003738',
+        30: '#004F51',
+        40: '#00696B',
+        50: '#008587',
+        60: '#00A1A3',
+        70: '#00BEC1',
+        80: '#2DDBDE',
+        90: '#8FF3F4',
+        95: '#B2FEFF',
+        99: '#F1FFFF',
+        100: '#FFFFFF',
+      },
+    },
+  },
+  // cssVarPrefix is only required if multiple themes coexist
+  // on the same page like on this guide
+  cssVarPrefix: 'turquoise-md3',
+});
+
+export default function MD3Theming() {
+  return (
+    <CssVarsProvider theme={customTheme}>
+      <Button color="primary" variant="filled">
+        Button
+      </Button>
+    </CssVarsProvider>
+  );
+}

docs/data/material/guides/material-3-components/MD3Theming.tsx.preview

@@ -0,0 +1,5 @@
+<CssVarsProvider theme={customTheme}>
+  <Button color="primary" variant="filled">
+    Button
+  </Button>
+</CssVarsProvider>