[core][docs] Restore and revise the Box docs (mui#40622)

docs/data/joy/components/box/BoxBasic.js

@@ -0,0 +1,10 @@
+import * as React from 'react';
+import Box from '@mui/joy/Box';
+
+export default function BoxBasic() {
+  return (
+    <Box component="section" sx={{ p: 2, border: '1px dashed grey' }}>
+      This Box renders as an HTML section element.
+    </Box>
+  );
+}

docs/data/joy/components/box/BoxBasic.tsx

@@ -0,0 +1,10 @@
+import * as React from 'react';
+import Box from '@mui/joy/Box';
+
+export default function BoxBasic() {
+  return (
+    <Box component="section" sx={{ p: 2, border: '1px dashed grey' }}>
+      This Box renders as an HTML section element.
+    </Box>
+  );
+}

docs/data/joy/components/box/BoxBasic.tsx.preview

@@ -0,0 +1,2 @@
+
+  This Box renders as an HTML section element.

docs/data/joy/components/box/BoxSx.js

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import { Box, ThemeProvider } from '@mui/joy';
+
+export default function BoxSx() {
+  return (
+    <ThemeProvider
+      theme={{
+        colorSchemes: {
+          light: {
+            palette: {
+              primary: {
+                400: '#38bdf8',
+                700: '#0369a1',
+              },
+            },
+          },
+        },
+      }}
+    >
+      <Box
+        sx={{
+          width: 100,
+          height: 100,
+          borderRadius: 1,
+          bgcolor: 'primary.700',
+          '&:hover': {
+            bgcolor: 'primary.400',
+          },
+        }}
+      />
+    </ThemeProvider>
+  );
+}

docs/data/joy/components/box/BoxSx.tsx

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import { Box, ThemeProvider } from '@mui/joy';
+
+export default function BoxSx() {
+  return (
+    <ThemeProvider
+      theme={{
+        colorSchemes: {
+          light: {
+            palette: {
+              primary: {
+                400: '#38bdf8',
+                700: '#0369a1',
+              },
+            },
+          },
+        },
+      }}
+    >
+      <Box
+        sx={{
+          width: 100,
+          height: 100,
+          borderRadius: 1,
+          bgcolor: 'primary.700',
+          '&:hover': {
+            bgcolor: 'primary.400',
+          },
+        }}
+      />
+    </ThemeProvider>
+  );
+}

docs/data/joy/components/box/BoxSystemProps.js

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import Box from '@mui/joy/Box';
+
+export default function BoxSystemProps() {
+  return (
+    <Box
+      height={200}
+      width={200}
+      my={4}
+      display="flex"
+      alignItems="center"
+      gap={4}
+      p={2}
+      sx={{ border: '2px solid grey' }}
+    >
+      This Box uses MUI System props for quick customization.
+    </Box>
+  );
+}

docs/data/joy/components/box/BoxSystemProps.tsx

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import Box from '@mui/joy/Box';
+
+export default function BoxSystemProps() {
+  return (
+    <Box
+      height={200}
+      width={200}
+      my={4}
+      display="flex"
+      alignItems="center"
+      gap={4}
+      p={2}
+      sx={{ border: '2px solid grey' }}
+    >
+      This Box uses MUI System props for quick customization.
+    </Box>
+  );
+}

docs/data/joy/components/box/BoxSystemProps.tsx.preview

@@ -0,0 +1,2 @@
+
+  This Box uses MUI System props for quick customization.

docs/data/joy/components/box/box.md

@@ -5,13 +5,57 @@ components: Box
 githubLabel: 'component: Box'
 ---
 
+<!-- This page's content is duplicated (with some product-specific details) across the Material UI, Joy UI, and MUI System docs. Any changes should be applied to all three pages at the same time. -->
+
 # Box
 
 <p class="description">The Box component is a generic, theme-aware container with access to CSS utilities from MUI System.</p>
 
-:::warning
-Please refer to the [Box](/system/react-box/) component page in the MUI System docs for demos and details on usage.
+{{"component": "modules/components/ComponentLinkHeader.js", "design": false}}
+
+## Introduction
+
+The Box component is a generic container for grouping other components.
+It's a fundamental building block when working with Joy UI—you can think of it as a `<div>` with extra built-in features, like access to your app's theme and the [`sx` prop](/system/getting-started/the-sx-prop/).
+
+### Usage
+
+The Box component differs from other containers available in Joy UI in that its usage is intended to be multipurpose and open-ended, just like a `<div>`.
+Components like [Stack](/joy-ui/react-stack/) and [Sheet](/joy-ui/react-sheet/), by contrast, feature usage-specific props that make them ideal for certain use cases: Stack for one-dimensional layouts, and Sheet for surfaces that need access to Joy UI's global variants.
+
+## Basics
+
+```jsx
+import Box from '@mui/joy/Box';
+```
+
+The Box component renders as a `<div>` by default, but you can swap in any other valid HTML tag or React component using the `component` prop.
+The demo below replaces the `<div>` with a `<section>` element:
+
+{{"demo": "BoxBasic.js", "defaultCodeOpen": true }}
+
+## Customization
+
+### With MUI System props
+
+As a CSS utility component, the Box supports all [MUI System properties](/system/properties/).
+You can use them as props directly on the component.
+
+{{"demo": "BoxSystemProps.js", "defaultCodeOpen": true }}
+
+### With the sx prop
+
+Use the [`sx` prop](/system/getting-started/the-sx-prop/) to quickly customize any Box instance using a superset of CSS that has access to all the style functions and theme-aware properties exposed in the MUI System package.
+The demo below shows how to apply colors from the theme using this prop:
+
+{{"demo": "BoxSx.js", "defaultCodeOpen": true }}
+
+## Anatomy
+
+The Box component is composed of a single root `<div>` element:
 
-The Box component is a part of the standalone [MUI System](/system/getting-started/) utility library.
-It is re-exported from `@mui/joy` for your convenience.
-:::
+```html
+<div className="MuiBox-root">
+  <!-- contents of the Box -->
+</div>
+```

docs/data/material/components/box/BoxBasic.js

@@ -0,0 +1,10 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+
+export default function BoxBasic() {
+  return (
+    <Box component="section" sx={{ p: 2, border: '1px dashed grey' }}>
+      This Box renders as an HTML section element.
+    </Box>
+  );
+}

docs/data/material/components/box/BoxBasic.tsx

@@ -0,0 +1,10 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+
+export default function BoxBasic() {
+  return (
+    <Box component="section" sx={{ p: 2, border: '1px dashed grey' }}>
+      This Box renders as an HTML section element.
+    </Box>
+  );
+}

docs/data/material/components/box/BoxBasic.tsx.preview

@@ -0,0 +1,2 @@
+
+  This Box renders as an HTML section element.

docs/data/material/components/box/BoxSx.js

@@ -1,18 +1,29 @@
 import * as React from 'react';
-import Box from '@mui/material/Box';
+import { Box, ThemeProvider } from '@mui/material';
 
 export default function BoxSx() {
   return (
-    <Box
-      sx={{
-        width: 300,
-        height: 300,
-        backgroundColor: 'primary.dark',
-        '&:hover': {
-          backgroundColor: 'primary.main',
-          opacity: [0.9, 0.8, 0.7],
+    <ThemeProvider
+      theme={{
+        palette: {
+          primary: {
+            main: '#007FFF',
+            dark: '#0066CC',
+          },
         },
       }}
-    />
+    >
+      <Box
+        sx={{
+          width: 100,
+          height: 100,
+          borderRadius: 1,
+          bgcolor: 'primary.main',
+          '&:hover': {
+            bgcolor: 'primary.dark',
+          },
+        }}
+      />
+    </ThemeProvider>
   );
 }

docs/data/material/components/box/BoxSx.tsx

@@ -1,18 +1,29 @@
 import * as React from 'react';
-import Box from '@mui/material/Box';
+import { Box, ThemeProvider } from '@mui/material';
 
 export default function BoxSx() {
   return (
-    <Box
-      sx={{
-        width: 300,
-        height: 300,
-        backgroundColor: 'primary.dark',
-        '&:hover': {
-          backgroundColor: 'primary.main',
-          opacity: [0.9, 0.8, 0.7],
+    <ThemeProvider
+      theme={{
+        palette: {
+          primary: {
+            main: '#007FFF',
+            dark: '#0066CC',
+          },
         },
       }}
-    />
+    >
+      <Box
+        sx={{
+          width: 100,
+          height: 100,
+          borderRadius: 1,
+          bgcolor: 'primary.main',
+          '&:hover': {
+            bgcolor: 'primary.dark',
+          },
+        }}
+      />
+    </ThemeProvider>
   );
 }

docs/data/material/components/box/BoxSystemProps.js

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+
+export default function BoxSystemProps() {
+  return (
+    <Box
+      height={200}
+      width={200}
+      my={4}
+      display="flex"
+      alignItems="center"
+      gap={4}
+      p={2}
+      sx={{ border: '2px solid grey' }}
+    >
+      This Box uses MUI System props for quick customization.
+    </Box>
+  );
+}

docs/data/material/components/box/BoxSystemProps.tsx

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+
+export default function BoxSystemProps() {
+  return (
+    <Box
+      height={200}
+      width={200}
+      my={4}
+      display="flex"
+      alignItems="center"
+      gap={4}
+      p={2}
+      sx={{ border: '2px solid grey' }}
+    >
+      This Box uses MUI System props for quick customization.
+    </Box>
+  );
+}

docs/data/material/components/box/BoxSystemProps.tsx.preview

@@ -0,0 +1,2 @@
+
+  This Box uses MUI System props for quick customization.