From 37bad2a88a44f9835e0cd927c38205f9209a16f0 Mon Sep 17 00:00:00 2001
From: Danilo Leal <67129314+danilo-leal@users.noreply.github.com>
Date: Mon, 4 Mar 2024 17:39:47 -0300
Subject: [PATCH] [system][docs] Tweak the Usage demos (#41242)

---
 .../data/system/getting-started/usage/Demo.js | 52 ++++++++++---------
 .../system/getting-started/usage/Demo.tsx     | 52 ++++++++++---------
 docs/data/system/getting-started/usage/Why.js | 24 +++++----
 .../data/system/getting-started/usage/Why.tsx | 24 +++++----
 .../system/getting-started/usage/usage.md     | 20 +++----
 5 files changed, 92 insertions(+), 80 deletions(-)

diff --git a/docs/data/system/getting-started/usage/Demo.js b/docs/data/system/getting-started/usage/Demo.js
index 1a667fb6092020..f07c23b3a7cc45 100644
--- a/docs/data/system/getting-started/usage/Demo.js
+++ b/docs/data/system/getting-started/usage/Demo.js
@@ -1,7 +1,5 @@
 import * as React from 'react';
-import Box from '@mui/material/Box';
-import { alpha } from '@mui/material/styles';
-import ErrorOutlineIcon from '@mui/icons-material/ErrorOutline';
+import Box from '@mui/system/Box';
 
 export default function Demo() {
   return (
@@ -10,11 +8,11 @@ export default function Demo() {
         display: 'flex',
         flexDirection: { xs: 'column', md: 'row' },
         alignItems: 'center',
-        bgcolor: 'background.paper',
-        overflow: 'hidden',
-        borderRadius: '12px',
-        boxShadow: 1,
-        fontWeight: 'bold',
+        bgcolor: 'background.default',
+        border: '1px solid',
+        borderColor: 'divider',
+        borderRadius: 2,
+        overflow: 'clip',
       }}
     >
       <Box
@@ -30,38 +28,42 @@ export default function Demo() {
       />
       <Box
         sx={{
+          p: 3,
+          minWidth: { md: 350 },
           display: 'flex',
           flexDirection: 'column',
           alignItems: { xs: 'center', md: 'flex-start' },
-          m: 3,
-          minWidth: { md: 350 },
+          gap: 0.5,
         }}
       >
-        <Box component="span" sx={{ fontSize: 16, mt: 1 }}>
+        <Box component="span" sx={{ fontSize: '0.875rem', color: 'text.secondary' }}>
           123 Main St, Phoenix AZ
         </Box>
-        <Box component="span" sx={{ color: 'primary.main', fontSize: 22 }}>
+        <Box
+          component="span"
+          sx={{ color: 'primary.main', fontSize: '1.5rem', fontWeight: 'bold' }}
+        >
           $280,000 — $310,000
         </Box>
         <Box
           sx={{
-            mt: 1.5,
-            p: 0.5,
-            backgroundColor: (theme) => alpha(theme.palette.primary.main, 0.1),
-            borderRadius: '5px',
-            color: 'primary.main',
-            fontWeight: 'medium',
+            py: 0.5,
+            px: 1,
+            backgroundColor: 'rgba(46, 125, 50, 0.1)',
+            borderRadius: 10,
             display: 'flex',
-            fontSize: 12,
             alignItems: 'center',
-            '& svg': {
-              fontSize: 21,
-              mr: 0.5,
-            },
+            gap: 0.5,
+            border: '1px solid',
+            borderColor: 'rgba(46, 125, 50, 0.1)',
+            fontSize: '0.7rem',
+            fontWeight: 'bold',
+            letterSpacing: '.05rem',
+            textTransform: 'uppercase',
+            color: 'success.main',
           }}
         >
-          <ErrorOutlineIcon />
-          CONFIDENCE SCORE 85%
+          Confidence score: 85%
         </Box>
       </Box>
     </Box>
diff --git a/docs/data/system/getting-started/usage/Demo.tsx b/docs/data/system/getting-started/usage/Demo.tsx
index 1a667fb6092020..f07c23b3a7cc45 100644
--- a/docs/data/system/getting-started/usage/Demo.tsx
+++ b/docs/data/system/getting-started/usage/Demo.tsx
@@ -1,7 +1,5 @@
 import * as React from 'react';
-import Box from '@mui/material/Box';
-import { alpha } from '@mui/material/styles';
-import ErrorOutlineIcon from '@mui/icons-material/ErrorOutline';
+import Box from '@mui/system/Box';
 
 export default function Demo() {
   return (
@@ -10,11 +8,11 @@ export default function Demo() {
         display: 'flex',
         flexDirection: { xs: 'column', md: 'row' },
         alignItems: 'center',
-        bgcolor: 'background.paper',
-        overflow: 'hidden',
-        borderRadius: '12px',
-        boxShadow: 1,
-        fontWeight: 'bold',
+        bgcolor: 'background.default',
+        border: '1px solid',
+        borderColor: 'divider',
+        borderRadius: 2,
+        overflow: 'clip',
       }}
     >
       <Box
@@ -30,38 +28,42 @@ export default function Demo() {
       />
       <Box
         sx={{
+          p: 3,
+          minWidth: { md: 350 },
           display: 'flex',
           flexDirection: 'column',
           alignItems: { xs: 'center', md: 'flex-start' },
-          m: 3,
-          minWidth: { md: 350 },
+          gap: 0.5,
         }}
       >
-        <Box component="span" sx={{ fontSize: 16, mt: 1 }}>
+        <Box component="span" sx={{ fontSize: '0.875rem', color: 'text.secondary' }}>
           123 Main St, Phoenix AZ
         </Box>
-        <Box component="span" sx={{ color: 'primary.main', fontSize: 22 }}>
+        <Box
+          component="span"
+          sx={{ color: 'primary.main', fontSize: '1.5rem', fontWeight: 'bold' }}
+        >
           $280,000 — $310,000
         </Box>
         <Box
           sx={{
-            mt: 1.5,
-            p: 0.5,
-            backgroundColor: (theme) => alpha(theme.palette.primary.main, 0.1),
-            borderRadius: '5px',
-            color: 'primary.main',
-            fontWeight: 'medium',
+            py: 0.5,
+            px: 1,
+            backgroundColor: 'rgba(46, 125, 50, 0.1)',
+            borderRadius: 10,
             display: 'flex',
-            fontSize: 12,
             alignItems: 'center',
-            '& svg': {
-              fontSize: 21,
-              mr: 0.5,
-            },
+            gap: 0.5,
+            border: '1px solid',
+            borderColor: 'rgba(46, 125, 50, 0.1)',
+            fontSize: '0.7rem',
+            fontWeight: 'bold',
+            letterSpacing: '.05rem',
+            textTransform: 'uppercase',
+            color: 'success.main',
           }}
         >
-          <ErrorOutlineIcon />
-          CONFIDENCE SCORE 85%
+          Confidence score: 85%
         </Box>
       </Box>
     </Box>
diff --git a/docs/data/system/getting-started/usage/Why.js b/docs/data/system/getting-started/usage/Why.js
index a2dc74962d8e61..dd6d81e8faa518 100644
--- a/docs/data/system/getting-started/usage/Why.js
+++ b/docs/data/system/getting-started/usage/Why.js
@@ -1,37 +1,41 @@
 import * as React from 'react';
 import TrendingUpIcon from '@mui/icons-material/TrendingUp';
-import Box from '@mui/material/Box';
+import Box from '@mui/system/Box';
 
 export default function Why() {
   return (
     <Box
       sx={{
-        bgcolor: 'background.paper',
-        boxShadow: 1,
-        borderRadius: 1,
         p: 2,
         minWidth: 300,
+        border: '1px solid',
+        borderColor: 'divider',
+        bgcolor: 'background.default',
+        borderRadius: 2,
       }}
     >
       <Box sx={{ color: 'text.secondary' }}>Sessions</Box>
-      <Box sx={{ color: 'text.primary', fontSize: 34, fontWeight: 'medium' }}>
+      <Box
+        sx={{ color: 'text.primary', fontSize: '2.125rem', fontWeight: 'medium' }}
+      >
         98.3 K
       </Box>
       <Box
         component={TrendingUpIcon}
-        sx={{ color: 'success.dark', fontSize: 16, verticalAlign: 'sub' }}
+        sx={{ color: 'success.dark', fontSize: '1rem', verticalAlign: 'sub' }}
       />
       <Box
         sx={{
-          color: 'success.dark',
           display: 'inline',
-          fontWeight: 'medium',
+          fontSize: '0.875rem',
+          fontWeight: 'bold',
+          color: 'success.dark',
           mx: 0.5,
         }}
       >
-        18.77%
+        18.7%
       </Box>
-      <Box sx={{ color: 'text.secondary', display: 'inline', fontSize: 12 }}>
+      <Box sx={{ color: 'text.secondary', display: 'inline', fontSize: '0.875rem' }}>
         vs. last week
       </Box>
     </Box>
diff --git a/docs/data/system/getting-started/usage/Why.tsx b/docs/data/system/getting-started/usage/Why.tsx
index a2dc74962d8e61..dd6d81e8faa518 100644
--- a/docs/data/system/getting-started/usage/Why.tsx
+++ b/docs/data/system/getting-started/usage/Why.tsx
@@ -1,37 +1,41 @@
 import * as React from 'react';
 import TrendingUpIcon from '@mui/icons-material/TrendingUp';
-import Box from '@mui/material/Box';
+import Box from '@mui/system/Box';
 
 export default function Why() {
   return (
     <Box
       sx={{
-        bgcolor: 'background.paper',
-        boxShadow: 1,
-        borderRadius: 1,
         p: 2,
         minWidth: 300,
+        border: '1px solid',
+        borderColor: 'divider',
+        bgcolor: 'background.default',
+        borderRadius: 2,
       }}
     >
       <Box sx={{ color: 'text.secondary' }}>Sessions</Box>
-      <Box sx={{ color: 'text.primary', fontSize: 34, fontWeight: 'medium' }}>
+      <Box
+        sx={{ color: 'text.primary', fontSize: '2.125rem', fontWeight: 'medium' }}
+      >
         98.3 K
       </Box>
       <Box
         component={TrendingUpIcon}
-        sx={{ color: 'success.dark', fontSize: 16, verticalAlign: 'sub' }}
+        sx={{ color: 'success.dark', fontSize: '1rem', verticalAlign: 'sub' }}
       />
       <Box
         sx={{
-          color: 'success.dark',
           display: 'inline',
-          fontWeight: 'medium',
+          fontSize: '0.875rem',
+          fontWeight: 'bold',
+          color: 'success.dark',
           mx: 0.5,
         }}
       >
-        18.77%
+        18.7%
       </Box>
-      <Box sx={{ color: 'text.secondary', display: 'inline', fontSize: 12 }}>
+      <Box sx={{ color: 'text.secondary', display: 'inline', fontSize: '0.875rem' }}>
         vs. last week
       </Box>
     </Box>
diff --git a/docs/data/system/getting-started/usage/usage.md b/docs/data/system/getting-started/usage/usage.md
index fe9bc02ec89078..611d8a91a22eba 100644
--- a/docs/data/system/getting-started/usage/usage.md
+++ b/docs/data/system/getting-started/usage/usage.md
@@ -152,18 +152,18 @@ It works with both Emotion and styled-components.
 
 #### Cons
 
-- Runtime performance takes a hit.
+Runtime performance takes a hit.
 
-  | Benchmark case                    | Code snippet          | Time normalized |
-  | :-------------------------------- | :-------------------- | --------------: |
-  | a. Render 1,000 primitives        | `<div className="…">` |           100ms |
-  | b. Render 1,000 components        | `<Div>`               |           112ms |
-  | c. Render 1,000 styled components | `<StyledDiv>`         |           181ms |
-  | d. Render 1,000 Box               | `<Box sx={…}>`        |           296ms |
+| Benchmark case                    | Code snippet          | Time normalized |
+| :-------------------------------- | :-------------------- | --------------: |
+| a. Render 1,000 primitives        | `<div className="…">` |           100ms |
+| b. Render 1,000 components        | `<Div>`               |           112ms |
+| c. Render 1,000 styled components | `<StyledDiv>`         |           181ms |
+| d. Render 1,000 Box               | `<Box sx={…}>`        |           296ms |
 
 <!-- #default-branch-switch -->
 
-_Head to the [benchmark folder](https://github.com/mui/material-ui/tree/master/benchmark/browser) for a reproduction of these metrics._
+Visit the [benchmark folder](https://github.com/mui/material-ui/tree/master/benchmark/browser) for a reproduction of the metrics above.
 
 We believe that for most use cases it's fast enough, but there are simple workarounds when performance becomes critical.
 For instance, when rendering a list with many items, you can use a CSS child selector to have a single "style injection" point (using d. for the wrapper and a. for each item).
@@ -183,7 +183,7 @@ The `sx` prop can be used in four different locations:
 
 ### Core components
 
-All Material UI, and Joy UI components support the `sx` prop.
+All Material UI and Joy UI components support the `sx` prop.
 
 ### Box
 
@@ -202,7 +202,7 @@ const Div = styled('div')``;
 
 ### Any element with the babel plugin
 
-TODO [#23220](https://github.com/mui/material-ui/issues/23220).
+Visit [the open GitHub issue](https://github.com/mui/material-ui/issues/23220) regarding this topic to learn more.
 
 ## How to use MUI System