more content and structure revisions

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

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import Paper from '@mui/material/Paper';
+import { styled } from '@mui/material/styles';
+
+const DemoPaper = styled(Paper)(({ theme }) => ({
+  ...theme.typography.body2,
+  textAlign: 'center',
+  color: theme.palette.text.secondary,
+  paddingTop: 20,
+}));
+
+export default function SquareCorners() {
+  return (
+    <Box
+      sx={{
+        display: 'flex',
+        '& > :not(style)': {
+          m: 1,
+          width: 128,
+          height: 128,
+        },
+      }}
+    >
+      <DemoPaper square={false}>
+        {' '}
+        {/* this is the default value */}
+        rounded corners
+      </DemoPaper>
+      <DemoPaper square>square corners</DemoPaper>
+    </Box>
+  );
+}

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

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import Paper from '@mui/material/Paper';
+import { styled } from '@mui/material/styles';
+
+const DemoPaper = styled(Paper)(({ theme }) => ({
+  ...theme.typography.body2,
+  textAlign: 'center',
+  color: theme.palette.text.secondary,
+  paddingTop: 20,
+}));
+
+export default function SquareCorners() {
+  return (
+    <Box
+      sx={{
+        display: 'flex',
+        '& > :not(style)': {
+          m: 1,
+          width: 128,
+          height: 128,
+        },
+      }}
+    >
+      <DemoPaper square={false}>
+        {' '}
+        {/* this is the default value */}
+        rounded corners
+      </DemoPaper>
+      <DemoPaper square>square corners</DemoPaper>
+    </Box>
+  );
+}

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

@@ -0,0 +1,6 @@
+<DemoPaper square={false}> {/* this is the default value */}
+  rounded corners
+</DemoPaper>
+<DemoPaper square>
+  square corners
+</DemoPaper>

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

@@ -1,6 +1,14 @@
 import * as React from 'react';
 import Box from '@mui/material/Box';
 import Paper from '@mui/material/Paper';
+import { styled } from '@mui/material/styles';
+
+const DemoPaper = styled(Paper)(({ theme }) => ({
+  ...theme.typography.body2,
+  textAlign: 'center',
+  color: theme.palette.text.secondary,
+  paddingTop: 20,
+}));
 
 export default function Variants() {
   return (
@@ -14,8 +22,12 @@ export default function Variants() {
         },
       }}
     >
-      <Paper variant="outlined" />
-      <Paper variant="outlined" square />
+      <DemoPaper variant="elevation">
+        {' '}
+        {/* this is the default value */}
+        default variant
+      </DemoPaper>
+      <DemoPaper variant="outlined">outlined variant</DemoPaper>
     </Box>
   );
 }

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

@@ -1,6 +1,14 @@
 import * as React from 'react';
 import Box from '@mui/material/Box';
 import Paper from '@mui/material/Paper';
+import { styled } from '@mui/material/styles';
+
+const DemoPaper = styled(Paper)(({ theme }) => ({
+  ...theme.typography.body2,
+  textAlign: 'center',
+  color: theme.palette.text.secondary,
+  paddingTop: 20,
+}));
 
 export default function Variants() {
   return (
@@ -14,8 +22,12 @@ export default function Variants() {
         },
       }}
     >
-      <Paper variant="outlined" />
-      <Paper variant="outlined" square />
+      <DemoPaper variant="elevation">
+        {' '}
+        {/* this is the default value */}
+        default variant
+      </DemoPaper>
+      <DemoPaper variant="outlined">outlined variant</DemoPaper>
     </Box>
   );
 }

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

@@ -1,2 +1,6 @@
-<Paper variant="outlined" />
-<Paper variant="outlined" square />
+<DemoPaper variant="elevation"> {/* this is the default value */}
+  default variant
+</DemoPaper>
+<DemoPaper variant="outlined">
+  outlined variant
+</DemoPaper>

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

@@ -8,45 +8,64 @@ 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>
+<p class="description">The Paper component is a container for displaying content on an elevated surface.</p>
 
 {{"component": "modules/components/ComponentLinkHeader.js"}}
 
 ## Introduction
 
-Material Design v2 surface components and shadow styling were heavily influenced by how these elements exist in the physical world.
+In Material Design, the physical properties of paper are translated to the screen. Surface components and shadow styles are heavily influenced by their real-world physical counterparts.
 
-Material UI picked that up by creating the Paper component, a general container-like surface that includes handy built-in props such as `elevation` that allows you to pull box-shadow values from the theme that adhere to [Material Design's elevation system](https://m2.material.io/design/environment/elevation.html#elevation-in-material-design).
+Material UI implements this concept with the Paper component, a general container-like surface that features the [`elevation`](#elevation) prop for pulling box-shadow values from the theme.
 
-## Component
+:::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.
 
-### Basic usage
+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.
+:::
 
-Note how the Paper component comes with a light elevation by default.
+## Component
 
 {{"demo": "SimplePaper.js", "bg": true}}
 
-### Variants
-
-Use the `variant` prop to toggle between an outlined version of the Paper component, without elevation, and an elevated version.
-
-{{"demo": "Variants.js", "bg": true}}
+## 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.
 
-Note that in dark mode, increasing the elevation also makes the background color lighter.
+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.
 
-:::info
-The dark mode behavior can lead to confusion when overriding the Paper component, as just changing the `background-color` property won't affect the lighter shading. To override it, either use a new background value or customize the values for both `background-color` and `background-image`.
+:::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"}}
 
-## When to use
+### Variants
+
+Set the `variant` prop to `"outlined"` for a flat, outlined Paper with no shadows:
+
+{{"demo": "Variants.js", "bg": true}}
+
+### Corners
+
+The Paper component features rounded corners by default.
+Add the `square` prop for square corners:
+
+{{"demo": "SquareCorners.js", "bg": true}}
+
+## Anatomy
 
-The Paper component is better suited if you want to follow Material Design's steps and try to replicate, on your app, how light casts shadows in the physical world through the use of a thoughtfully designed elevation scale.
+The Paper component is composed of a single root `<div>` that wraps around its contents:
 
-If that's not the case, other general layout components may suffice, like the [Box](/material-ui/react-box/) and [Container](/material-ui/react-container/) components.
+```html
+<div class="MuiPaper-root">
+  <!-- Paper contents -->
+</div>
+```