[docs][material-ui] Revise the Paper component docs (#38841)

Co-authored-by: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>

docs/data/material/components/paper/Elevation.js

@@ -24,6 +24,7 @@ export default function Elevation() {
             <Box
               sx={{
                 p: 2,
+                borderRadius: 2,
                 bgcolor: 'background.default',
                 display: 'grid',
                 gridTemplateColumns: { md: '1fr 1fr' },

docs/data/material/components/paper/Elevation.tsx

@@ -24,6 +24,7 @@ export default function Elevation() {
             <Box
               sx={{
                 p: 2,
+                borderRadius: 2,
                 bgcolor: 'background.default',
                 display: 'grid',
                 gridTemplateColumns: { md: '1fr 1fr' },

docs/data/material/components/paper/SquareCorners.js

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import Stack from '@mui/material/Stack';
+import Paper from '@mui/material/Paper';
+import { styled } from '@mui/material/styles';
+
+const DemoPaper = styled(Paper)(({ theme }) => ({
+  width: 120,
+  height: 120,
+  padding: theme.spacing(2),
+  ...theme.typography.body2,
+  textAlign: 'center',
+}));
+
+export default function SquareCorners() {
+  return (
+    <Stack direction="row" spacing={2}>
+      <DemoPaper square={false}>rounded corners</DemoPaper>
+      <DemoPaper square>square corners</DemoPaper>
+    </Stack>
+  );
+}

docs/data/material/components/paper/SquareCorners.tsx

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import Stack from '@mui/material/Stack';
+import Paper from '@mui/material/Paper';
+import { styled } from '@mui/material/styles';
+
+const DemoPaper = styled(Paper)(({ theme }) => ({
+  width: 120,
+  height: 120,
+  padding: theme.spacing(2),
+  ...theme.typography.body2,
+  textAlign: 'center',
+}));
+
+export default function SquareCorners() {
+  return (
+    <Stack direction="row" spacing={2}>
+      <DemoPaper square={false}>rounded corners</DemoPaper>
+      <DemoPaper square>square corners</DemoPaper>
+    </Stack>
+  );
+}

docs/data/material/components/paper/SquareCorners.tsx.preview

@@ -0,0 +1,2 @@
+<DemoPaper square={false}>rounded corners</DemoPaper>
+<DemoPaper square>square corners</DemoPaper>

docs/data/material/components/paper/Variants.js

@@ -1,21 +1,21 @@
 import * as React from 'react';
-import Box from '@mui/material/Box';
+import Stack from '@mui/material/Stack';
 import Paper from '@mui/material/Paper';
+import { styled } from '@mui/material/styles';
+
+const DemoPaper = styled(Paper)(({ theme }) => ({
+  width: 120,
+  height: 120,
+  padding: theme.spacing(2),
+  ...theme.typography.body2,
+  textAlign: 'center',
+}));
 
 export default function Variants() {
   return (
-    <Box
-      sx={{
-        display: 'flex',
-        '& > :not(style)': {
-          m: 1,
-          width: 128,
-          height: 128,
-        },
-      }}
-    >
-      <Paper variant="outlined" />
-      <Paper variant="outlined" square />
-    </Box>
+    <Stack direction="row" spacing={2}>
+      <DemoPaper variant="elevation">default variant</DemoPaper>
+      <DemoPaper variant="outlined">outlined variant</DemoPaper>
+    </Stack>
   );
 }

docs/data/material/components/paper/Variants.tsx

@@ -1,21 +1,21 @@
 import * as React from 'react';
-import Box from '@mui/material/Box';
+import Stack from '@mui/material/Stack';
 import Paper from '@mui/material/Paper';
+import { styled } from '@mui/material/styles';
+
+const DemoPaper = styled(Paper)(({ theme }) => ({
+  width: 120,
+  height: 120,
+  padding: theme.spacing(2),
+  ...theme.typography.body2,
+  textAlign: 'center',
+}));
 
 export default function Variants() {
   return (
-    <Box
-      sx={{
-        display: 'flex',
-        '& > :not(style)': {
-          m: 1,
-          width: 128,
-          height: 128,
-        },
-      }}
-    >
-      <Paper variant="outlined" />
-      <Paper variant="outlined" square />
-    </Box>
+    <Stack direction="row" spacing={2}>
+      <DemoPaper variant="elevation">default variant</DemoPaper>
+      <DemoPaper variant="outlined">outlined variant</DemoPaper>
+    </Stack>
   );
 }

docs/data/material/components/paper/Variants.tsx.preview

@@ -1,2 +1,2 @@
-<Paper variant="outlined" />
-<Paper variant="outlined" square />
+<DemoPaper variant="elevation">default variant</DemoPaper>
+<DemoPaper variant="outlined">outlined variant</DemoPaper>

docs/data/material/components/paper/paper.md

@@ -8,28 +8,68 @@ materialDesign: https://m2.material.io/design/environment/elevation.html
 
 # Paper
 
-<p class="description">In Material Design, the physical properties of paper are translated to the screen. </p>
-
-The background of an application resembles the flat, opaque texture of a sheet of paper, and an application's behavior mimics paper's ability to be re-sized, shuffled, and bound together in multiple sheets.
+<p class="description">The Paper component is a container for displaying content on an elevated surface.</p>
 
 {{"component": "modules/components/ComponentLinkHeader.js"}}
 
-## Basic paper
+## Introduction
+
+In Material Design, surface components and shadow styles are heavily influenced by their real-world physical counterparts.
+
+Material UI implements this concept with the Paper component, a container-like surface that features the [`elevation`](#elevation) prop for pulling box-shadow values from the theme.
+
+:::success
+The Paper component is ideally suited for designs that follow [Material Design's elevation system](https://m2.material.io/design/environment/elevation.html#elevation-in-material-design), which is meant to replicate how light casts shadows in the physical world.
+
+If you just need a generic container, you may prefer to use the [Box](/material-ui/react-box/) or [Container](/material-ui/react-container/) components.
+:::
 
 {{"demo": "SimplePaper.js", "bg": true}}
 
-## Variants
+## Component
+
+```jsx
+import Paper from '@mui/material/Paper';
+```
+
+## Customization
+
+### Elevation
+
+Use the `elevation` prop to establish hierarchy through the use of shadows.
+The Paper component's default elevation level is `1`.
+The prop accepts values from `0` to `24`.
+The higher the number, the further away the Paper appears to be from its background.
+
+In dark mode, increasing the elevation also makes the background color lighter.
+This is done by applying a semi-transparent gradient with the `background-image` CSS property.
+
+:::warning
+The aforementioned dark mode behavior can lead to confusion when overriding the Paper component, because changing the `background-color` property won't affect the lighter shading.
+To override it, you must either use a new background value, or customize the values for both `background-color` and `background-image`.
+:::
+
+{{"demo": "Elevation.js", "bg": "outlined"}}
+
+### Variants
+
+Set the `variant` prop to `"outlined"` for a flat, outlined Paper with no shadows:
+
+{{"demo": "Variants.js", "bg": true}}
 
-If you need an outlined surface, use the `variant` prop.
+### Corners
 
-{{"demo": "Variants.js", "bg": "inline"}}
+The Paper component features rounded corners by default.
+Add the `square` prop for square corners:
 
-## Elevation
+{{"demo": "SquareCorners.js", "bg": true}}
 
-The elevation can be used to establish a hierarchy between other content. In practical terms, the elevation controls the size of the shadow applied to the surface. In dark mode, raising the elevation also makes the surface lighter.
+## Anatomy
 
-{{"demo": "Elevation.js", "bg": "inline"}}
+The Paper component is composed of a single root `<div>` that wraps around its contents:
 
-The change of shade in dark mode is done by applying a semi-transparent gradient to the `background-image` property.
-This can lead to confusion when overriding the styles of `Paper`, as setting just the `background-color` property will not affect the elevation-related shading.
-To ignore the shading and set the background color that is not affected by elevation in dark mode, override the `background` property (or both `background-color` and `background-image`).
+```html
+<div class="MuiPaper-root">
+  <!-- Paper contents -->
+</div>
+```

docs/src/modules/components/Demo.js

@@ -233,7 +233,7 @@ const DemoRootMaterial = styled('div', {
     backgroundColor: (theme.vars || theme).palette.grey[50],
     border: `1px solid ${(theme.vars || theme).palette.divider}`,
     ...theme.applyDarkStyles({
-      backgroundColor: alpha(theme.palette.primaryDark[700], 0.5),
+      backgroundColor: alpha(theme.palette.primaryDark[700], 0.3),
     }),
   }),
   /* Mostly meant for introduction demos. */