From 31292a8bc69e8b61b10bd23f2850c66ecd2d5343 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ver=C3=B3nica=20Mil=C3=A1n?= <vmilan@cartodb.com>
Date: Wed, 26 Jul 2023 16:08:50 +0200
Subject: [PATCH] update status and stories

---
 UPGRADE.md                                    |  38 ++++
 .../storybook/stories/atoms/Button.stories.js |  14 +-
 .../stories/atoms/Text-field.stories.js       |  18 +-
 .../stories/foundations/Borders.stories.js    |   6 +-
 .../stories/foundations/Elevations.stories.js |   7 +-
 .../stories/foundations/Spacing.stories.js    |  12 +-
 .../stories/foundations/Typography.stories.js |  16 +-
 .../stories/molecules/Accordion.stories.js    |  26 ++-
 .../stories/molecules/Avatar.stories.js       |  42 +++-
 .../stories/molecules/Tooltip.stories.js      |  14 +-
 .../stories/organisms/AppBar.stories.js       |  14 +-
 .../stories/organisms/List.stories.js         | 180 ++++++++++--------
 .../organisms/ListItemGuide.stories.mdx       |  35 ++++
 .../stories/organisms/Menu.stories.js         |  28 +++
 .../react-ui/storybook/utils/storyStyles.js   |  21 +-
 15 files changed, 322 insertions(+), 149 deletions(-)
 create mode 100644 packages/react-ui/storybook/stories/organisms/ListItemGuide.stories.mdx

diff --git a/UPGRADE.md b/UPGRADE.md
index 01bc985af..fe7612a5c 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -139,6 +139,44 @@ We have a new component for building data structures within Tooltips, `TooltipDa
 
 # Components
 
+## Good practices
+
+### ListItem
+
+In order to be interactive, you need to use `MenuItem` component, or use `ListItemButton`instead.
+
+```
+<List>
+  <ListItemButton>
+    <ListItemIcon>
+      <Icon />
+    </ListItemIcon>
+    <ListItemText primary="List item text" />
+  </ListItemButton>
+<List>
+```
+
+```
+<MenuList>
+  <MenuItem>
+    <ListItemIcon>
+      <Icon />
+    </ListItemIcon>
+    <ListItemText primary="List item text" />
+  </MenuItem>
+<MenuList>
+```
+
+To render a link:
+
+```
+<ListItemButton component="a">
+  <ListItemText primary="List item text" />
+</ListItemButton>
+```
+
+Note that `<ListItem button />` is deprecated.
+
 ## Mui components replacement
 
 These components should be imported from carto-react library instead of Mui, as they replace the Mui components extending their functionality to meet with design criteria.
diff --git a/packages/react-ui/storybook/stories/atoms/Button.stories.js b/packages/react-ui/storybook/stories/atoms/Button.stories.js
index e88e600c5..d80a622c8 100644
--- a/packages/react-ui/storybook/stories/atoms/Button.stories.js
+++ b/packages/react-ui/storybook/stories/atoms/Button.stories.js
@@ -4,7 +4,7 @@ import { Add, Close } from '@mui/icons-material';
 import LoadingButton from '@mui/lab/LoadingButton';
 import Typography from '../../../src/components/atoms/Typography';
 import Button from '../../../src/components/atoms/Button';
-import { DocContainer, DocTextHighlight, DocLink } from '../../utils/storyStyles';
+import { DocContainer, DocHighlight, DocLink } from '../../utils/storyStyles';
 
 const options = {
   title: 'Atoms/Button',
@@ -213,17 +213,15 @@ const DocTemplate = () => {
       </DocLink>{' '}
       component that uses <i>Mui Button</i> and wraps its children in a <i>Typography</i>{' '}
       component to meet with the designed behavior (text overflow case).
-      <Typography variant='inherit' color='inherit' mt={2}>
+      <Typography mt={2}>
         So, instead of Mui Button, you should use this one:{' '}
-        <DocTextHighlight variant='inherit' component='span'>
-          react-ui/src/components/atoms/Button
-        </DocTextHighlight>
+        <DocHighlight component='span'>react-ui/src/components/atoms/Button</DocHighlight>
       </Typography>
-      <Typography variant='inherit' color='inherit' mt={2}>
+      <Typography mt={2}>
         For external use:{' '}
-        <DocTextHighlight variant='inherit' component='span'>
+        <DocHighlight component='span'>
           {'import { Button } from "@carto/react-ui";'}
-        </DocTextHighlight>
+        </DocHighlight>
         .
       </Typography>
     </DocContainer>
diff --git a/packages/react-ui/storybook/stories/atoms/Text-field.stories.js b/packages/react-ui/storybook/stories/atoms/Text-field.stories.js
index 86f608b79..dc1748712 100644
--- a/packages/react-ui/storybook/stories/atoms/Text-field.stories.js
+++ b/packages/react-ui/storybook/stories/atoms/Text-field.stories.js
@@ -3,12 +3,7 @@ import { Grid, InputAdornment, TextField } from '@mui/material';
 import React from 'react';
 import PasswordField from '../../../src/components/atoms/PasswordField';
 import Typography from '../../../src/components/atoms/Typography';
-import {
-  Container,
-  DocContainer,
-  DocTextHighlight,
-  Label
-} from '../../utils/storyStyles';
+import { Container, DocContainer, DocHighlight, Label } from '../../utils/storyStyles';
 
 const options = {
   title: 'Atoms/Text Field',
@@ -543,14 +538,9 @@ const PasswordFieldTemplate = ({
     <Grid container direction='column' spacing={6}>
       <Grid item>
         <DocContainer severity='warning'>
-          Use{' '}
-          <DocTextHighlight variant='inherit' component='span'>
-            {'<PasswordField />'}
-          </DocTextHighlight>{' '}
-          instead of{' '}
-          <DocTextHighlight variant='inherit' component='span'>
-            {'<TextField type="password" />'}
-          </DocTextHighlight>{' '}
+          Use <DocHighlight component='span'>{'<PasswordField />'}</DocHighlight> instead
+          of{' '}
+          <DocHighlight component='span'>{'<TextField type="password" />'}</DocHighlight>{' '}
           This component build the show / hide content logic on top of <i>TextField</i>{' '}
           Mui component.
         </DocContainer>
diff --git a/packages/react-ui/storybook/stories/foundations/Borders.stories.js b/packages/react-ui/storybook/stories/foundations/Borders.stories.js
index 813bc9cf9..68b8fb919 100644
--- a/packages/react-ui/storybook/stories/foundations/Borders.stories.js
+++ b/packages/react-ui/storybook/stories/foundations/Borders.stories.js
@@ -2,7 +2,7 @@ import React from 'react';
 import { Box, Grid } from '@mui/material';
 import { useTheme } from '@mui/material/styles';
 import Typography from '../../../src/components/atoms/Typography';
-import { DocContainer, FilledContainer } from '../../utils/storyStyles';
+import { DocContainer, DocHighlight, FilledContainer } from '../../utils/storyStyles';
 
 const options = {
   title: 'Foundations/Borders',
@@ -64,9 +64,7 @@ const DocTemplate = () => {
   return (
     <DocContainer severity='warning'>
       Use is restringed to a few specific values, defined in the design system, which are:{' '}
-      <Typography variant='code3' weight='strong'>
-        0.5, 1, 1.5, 2
-      </Typography>
+      <DocHighlight component='span'>0.5, 1, 1.5, 2</DocHighlight>
     </DocContainer>
   );
 };
diff --git a/packages/react-ui/storybook/stories/foundations/Elevations.stories.js b/packages/react-ui/storybook/stories/foundations/Elevations.stories.js
index a67452fef..6944cf7dd 100644
--- a/packages/react-ui/storybook/stories/foundations/Elevations.stories.js
+++ b/packages/react-ui/storybook/stories/foundations/Elevations.stories.js
@@ -2,7 +2,7 @@ import React from 'react';
 import { Box, Grid } from '@mui/material';
 import { useTheme } from '@mui/material/styles';
 import Typography from '../../../src/components/atoms/Typography';
-import { DocContainer, FilledContainer } from '../../utils/storyStyles';
+import { DocContainer, DocHighlight, FilledContainer } from '../../utils/storyStyles';
 
 const options = {
   title: 'Foundations/Elevations',
@@ -71,10 +71,7 @@ const DocTemplate = () => {
   return (
     <DocContainer severity='warning'>
       Use is restringed to a few specific values, defined in the design system, which are:{' '}
-      <Typography variant='code3' weight='strong'>
-        0, 1, 2, 4, 6, 8, 16, 24
-      </Typography>
-      .
+      <DocHighlight component='span'>0, 1, 2, 4, 6, 8, 16, 24</DocHighlight>.
     </DocContainer>
   );
 };
diff --git a/packages/react-ui/storybook/stories/foundations/Spacing.stories.js b/packages/react-ui/storybook/stories/foundations/Spacing.stories.js
index 189f4008c..1cf77d1c1 100644
--- a/packages/react-ui/storybook/stories/foundations/Spacing.stories.js
+++ b/packages/react-ui/storybook/stories/foundations/Spacing.stories.js
@@ -3,7 +3,7 @@ import { Box, Grid } from '@mui/material';
 import { useTheme } from '@mui/material/styles';
 import Typography from '../../../src/components/atoms/Typography';
 import Button from '../../../src/components/atoms/Button';
-import { DocContainer, DocTextHighlight, FilledContainer } from '../../utils/storyStyles';
+import { DocContainer, DocHighlight, FilledContainer } from '../../utils/storyStyles';
 
 const options = {
   title: 'Foundations/Spacing',
@@ -88,14 +88,8 @@ const DocTemplate = () => {
       }
     >
       Check the usage guide before using{' '}
-      <DocTextHighlight variant='inherit' component='span'>
-        spacing
-      </DocTextHighlight>{' '}
-      values, specially{' '}
-      <DocTextHighlight variant='inherit' component='span'>
-        theme.spacing
-      </DocTextHighlight>{' '}
-      function.
+      <DocHighlight component='span'>spacing</DocHighlight> values, specially{' '}
+      <DocHighlight component='span'>theme.spacing</DocHighlight> function.
     </DocContainer>
   );
 };
diff --git a/packages/react-ui/storybook/stories/foundations/Typography.stories.js b/packages/react-ui/storybook/stories/foundations/Typography.stories.js
index 82854d9ae..04624a6f0 100644
--- a/packages/react-ui/storybook/stories/foundations/Typography.stories.js
+++ b/packages/react-ui/storybook/stories/foundations/Typography.stories.js
@@ -1,7 +1,7 @@
 import React from 'react';
 import Typography from '../../../src/components/atoms/Typography';
 import ButtonComp from '../../../src/components/atoms/Button';
-import { DocContainer, DocLink, DocTextHighlight } from '../../utils/storyStyles';
+import { DocContainer, DocLink, DocHighlight } from '../../utils/storyStyles';
 
 const options = {
   title: 'Foundations/Typography',
@@ -94,20 +94,20 @@ const DocTemplate = () => {
         Typography
       </DocLink>{' '}
       component that extends <i>Mui Typography</i> with some styling props.
-      <Typography variant='inherit' color='inherit' mt={2}>
+      <Typography mt={2}>
         So, instead of Mui Typography, you should use this one:{' '}
-        <DocTextHighlight variant='inherit' component='span'>
+        <DocHighlight component='span'>
           react-ui/src/components/atoms/Typography
-        </DocTextHighlight>
+        </DocHighlight>
       </Typography>
-      <Typography variant='inherit' color='inherit' mt={2}>
+      <Typography mt={2}>
         For external use:{' '}
-        <DocTextHighlight variant='inherit' component='span'>
+        <DocHighlight component='span'>
           {'import { Typography } from "@carto/react-ui";'}
-        </DocTextHighlight>
+        </DocHighlight>
         .
       </Typography>
-      <Typography variant='inherit' color='inherit' mt={2} mb={2}>
+      <Typography mt={2} mb={2}>
         For more details, check the usage guide before using CARTO Typography
       </Typography>
     </DocContainer>
diff --git a/packages/react-ui/storybook/stories/molecules/Accordion.stories.js b/packages/react-ui/storybook/stories/molecules/Accordion.stories.js
index 86b267ffd..d2cd158b4 100644
--- a/packages/react-ui/storybook/stories/molecules/Accordion.stories.js
+++ b/packages/react-ui/storybook/stories/molecules/Accordion.stories.js
@@ -8,7 +8,12 @@ import {
   Grid
 } from '@mui/material';
 import { Typography } from '@carto/react-ui';
-import { BoxContent, TitleContent } from '../../utils/storyStyles';
+import {
+  BoxContent,
+  DocContainer,
+  DocHighlight,
+  TitleContent
+} from '../../utils/storyStyles';
 import AccordionGroup from '../../../src/components/molecules/AccordionGroup';
 
 const options = {
@@ -103,6 +108,25 @@ const GroupTemplate = ({ defaultExpanded, ...args }) => {
   return (
     <Grid container direction='column' spacing={3}>
       <Grid item>
+        <DocContainer severity='warning'>
+          Component used as a container of a group of `Mui Accordions`, that also adds a{' '}
+          <DocHighlight component='span'>variant</DocHighlight> prop to have different
+          styles in the group: <i>Standard (default)</i> and <i>Outlined</i>.
+          <Typography mt={2}>
+            Use <i>AccordionGroup</i> from:{' '}
+            <DocHighlight component='span'>
+              react-ui/src/components/molecules/AccordionGroup
+            </DocHighlight>
+          </Typography>
+          <Typography mt={2}>
+            For external use:{' '}
+            <DocHighlight component='span'>
+              {'import { AccordionGroup } from "@carto/react-ui";'}
+            </DocHighlight>
+            .
+          </Typography>
+        </DocContainer>
+
         <TitleContent variant='subtitle1'>
           {'AccordionGroup custom component'}
         </TitleContent>
diff --git a/packages/react-ui/storybook/stories/molecules/Avatar.stories.js b/packages/react-ui/storybook/stories/molecules/Avatar.stories.js
index 92690f991..5396c89f0 100644
--- a/packages/react-ui/storybook/stories/molecules/Avatar.stories.js
+++ b/packages/react-ui/storybook/stories/molecules/Avatar.stories.js
@@ -2,7 +2,14 @@ import React from 'react';
 import { Grid, useTheme } from '@mui/material';
 import { Star } from '@mui/icons-material';
 import { getCartoColorStylePropsForItem, Avatar } from '@carto/react-ui';
-import { BoxContent, TitleContent } from '../../utils/storyStyles';
+import {
+  BoxContent,
+  DocContainer,
+  DocLink,
+  DocHighlight,
+  TitleContent
+} from '../../utils/storyStyles';
+import Typography from '../../../src/components/atoms/Typography';
 
 const options = {
   title: 'Molecules/Avatar',
@@ -326,6 +333,37 @@ const ColorBackgroundTemplate = ({ ...args }) => {
   );
 };
 
+const DocTemplate = () => {
+  return (
+    <DocContainer severity='warning'>
+      We have our own{' '}
+      <DocLink href='https://github.com/CartoDB/carto-react/blob/master/packages/react-ui/src/components/molecules/Avatar.js'>
+        Avatar
+      </DocLink>{' '}
+      component that uses <i>Mui Avatar</i> and extends it with a new styling prop,{' '}
+      <DocHighlight component='span'>size</DocHighlight>.
+      <Typography mt={2}>
+        This component normalize <i>size</i> and allow us to use only the 4 sizes defined
+        by the design system:{' '}
+        <DocHighlight component='span'>large, medium, small and xsmall</DocHighlight>
+      </Typography>
+      <Typography mt={2}>
+        Import it from{' '}
+        <DocHighlight component='span'>
+          react-ui/src/components/molecules/Avatar
+        </DocHighlight>
+      </Typography>
+      <Typography mt={2}>
+        For external use:{' '}
+        <DocHighlight component='span'>
+          {'import { Avatar } from "@carto/react-ui";'}
+        </DocHighlight>
+        .
+      </Typography>
+    </DocContainer>
+  );
+};
+
 const disabledVariantArgType = {
   variant: { table: { disable: true } }
 };
@@ -335,6 +373,8 @@ const disabledSizeArgType = {
 
 export const Playground = Template.bind({});
 
+export const Guide = DocTemplate.bind({});
+
 export const Shape = ShapeTemplate.bind({});
 Shape.argTypes = disabledVariantArgType;
 
diff --git a/packages/react-ui/storybook/stories/molecules/Tooltip.stories.js b/packages/react-ui/storybook/stories/molecules/Tooltip.stories.js
index 98ce8082f..eaf03abbf 100644
--- a/packages/react-ui/storybook/stories/molecules/Tooltip.stories.js
+++ b/packages/react-ui/storybook/stories/molecules/Tooltip.stories.js
@@ -7,7 +7,7 @@ import { commonPalette } from '../../../src/theme/sections/palette';
 import {
   Container,
   DocContainer,
-  DocTextHighlight,
+  DocHighlight,
   Label,
   Standalone
 } from '../../utils/storyStyles';
@@ -239,15 +239,9 @@ const TooltipBehaviorTemplate = (args) => {
 const DocTemplate = () => {
   return (
     <DocContainer severity='warning'>
-      By default a Tooltip is placed{' '}
-      <DocTextHighlight variant='inherit' component='span'>
-        top
-      </DocTextHighlight>{' '}
-      and has an{' '}
-      <DocTextHighlight variant='inherit' component='span'>
-        arrow
-      </DocTextHighlight>{' '}
-      indicator, so you don't need to specify these properties anymore.
+      By default a Tooltip is placed <DocHighlight component='span'>top</DocHighlight> and
+      has an <DocHighlight component='span'>arrow</DocHighlight> indicator, so you don't
+      need to specify these properties anymore.
     </DocContainer>
   );
 };
diff --git a/packages/react-ui/storybook/stories/organisms/AppBar.stories.js b/packages/react-ui/storybook/stories/organisms/AppBar.stories.js
index 20eb61f08..c82a7240e 100644
--- a/packages/react-ui/storybook/stories/organisms/AppBar.stories.js
+++ b/packages/react-ui/storybook/stories/organisms/AppBar.stories.js
@@ -3,7 +3,7 @@ import { Avatar, Chip, Grid, IconButton, Menu, MenuItem } from '@mui/material';
 import { CheckCircleOutline } from '@mui/icons-material';
 import AppBar from '../../../src/components/organisms/AppBar/AppBar';
 import Typography from '../../../src/components/atoms/Typography';
-import { DocContainer, DocLink, DocTextHighlight } from '../../utils/storyStyles';
+import { DocContainer, DocLink, DocHighlight } from '../../utils/storyStyles';
 
 const options = {
   title: 'Organisms/AppBar',
@@ -100,17 +100,17 @@ const DocTemplate = () => {
       to build the basic structure and styles on top of <i>Mui AppBar</i>. It normalizes
       the size and position of common elements like:{' '}
       <i>logo, texts, avatar and burger menu icon</i>.
-      <Typography variant='inherit' color='inherit' mt={2}>
+      <Typography mt={2}>
         So, instead of Mui AppBar, you should use this one:{' '}
-        <DocTextHighlight variant='inherit' component='span'>
+        <DocHighlight component='span'>
           react-ui/src/components/organisms/AppBar
-        </DocTextHighlight>
+        </DocHighlight>
       </Typography>
-      <Typography variant='inherit' color='inherit' mt={2}>
+      <Typography mt={2}>
         For external use:{' '}
-        <DocTextHighlight variant='inherit' component='span'>
+        <DocHighlight component='span'>
           {'import { AppBar } from "@carto/react-ui";'}
-        </DocTextHighlight>
+        </DocHighlight>
         .
       </Typography>
     </DocContainer>
diff --git a/packages/react-ui/storybook/stories/organisms/List.stories.js b/packages/react-ui/storybook/stories/organisms/List.stories.js
index af4dad282..745f0d985 100644
--- a/packages/react-ui/storybook/stories/organisms/List.stories.js
+++ b/packages/react-ui/storybook/stories/organisms/List.stories.js
@@ -8,7 +8,6 @@ import {
   Grid,
   IconButton,
   List,
-  ListItem,
   ListItemAvatar,
   ListItemIcon,
   ListItemSecondaryAction,
@@ -16,7 +15,8 @@ import {
   Typography,
   Switch,
   Paper,
-  styled
+  styled,
+  ListItemButton
 } from '@mui/material';
 import {
   Drafts,
@@ -27,6 +27,8 @@ import {
   Inbox,
   Star
 } from '@mui/icons-material';
+import { DocContainer, DocHighlight } from '../../utils/storyStyles';
+import Button from '../../../src/components/atoms/Button';
 
 const options = {
   title: 'Organisms/List',
@@ -56,17 +58,17 @@ const Template = ({ secondary, ...args }) => {
         <Grid item xs={3}>
           <Paper>
             <List component='nav' aria-label='main mailbox folders'>
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Home' secondary={secondary} />
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Inbox' secondary={secondary} />
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Drafts' secondary={secondary} />
-              </ListItem>
+              </ListItemButton>
             </List>
           </Paper>
         </Grid>
@@ -74,26 +76,26 @@ const Template = ({ secondary, ...args }) => {
         <Grid item xs={3}>
           <Paper>
             <List component='nav' aria-label='main mailbox folders'>
-              <ListItem button>
+              <ListItemButton>
                 <ListItemIcon>
                   <Home />
                 </ListItemIcon>
                 <ListItemText primary='Home' secondary={secondary} />
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemIcon>
                   <Inbox />
                 </ListItemIcon>
                 <ListItemText primary='Inbox' secondary={secondary} />
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemIcon>
                   <Drafts />
                 </ListItemIcon>
                 <ListItemText primary='Drafts' secondary={secondary} />
-              </ListItem>
+              </ListItemButton>
             </List>
           </Paper>
         </Grid>
@@ -101,26 +103,26 @@ const Template = ({ secondary, ...args }) => {
         <Grid item xs={3}>
           <Paper>
             <List component='nav' aria-label='main mailbox folders'>
-              <ListItem button>
+              <ListItemButton>
                 <ListItemIcon>
                   <Checkbox edge='start' />
                 </ListItemIcon>
                 <ListItemText primary='Home' secondary={secondary} />
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemIcon>
                   <Checkbox edge='start' />
                 </ListItemIcon>
                 <ListItemText primary='Inbox' secondary={secondary} />
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemIcon>
                   <Checkbox edge='start' />
                 </ListItemIcon>
                 <ListItemText primary='Drafts' secondary={secondary} />
-              </ListItem>
+              </ListItemButton>
             </List>
           </Paper>
         </Grid>
@@ -128,32 +130,32 @@ const Template = ({ secondary, ...args }) => {
         <Grid item xs={3}>
           <Paper>
             <List component='nav' aria-label='main mailbox folders'>
-              <ListItem button>
+              <ListItemButton>
                 <ListItemAvatar>
                   <Avatar>
                     <Star />
                   </Avatar>
                 </ListItemAvatar>
                 <ListItemText primary='Home' secondary={secondary} />
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemAvatar>
                   <Avatar>
                     <Star />
                   </Avatar>
                 </ListItemAvatar>
                 <ListItemText primary='Inbox' secondary={secondary} />
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemAvatar>
                   <Avatar>
                     <Star />
                   </Avatar>
                 </ListItemAvatar>
                 <ListItemText primary='Drafts' secondary={secondary} />
-              </ListItem>
+              </ListItemButton>
             </List>
           </Paper>
         </Grid>
@@ -179,20 +181,20 @@ const TemplateMetaValue = ({ secondary, ...args }) => {
         <Grid item xs={3}>
           <Paper>
             <List component='nav' aria-label='main mailbox folders'>
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Home' />
                 <MetaValueLabel value={args.metaValue}></MetaValueLabel>
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Inbox' />
                 <MetaValueLabel value={args.metaValue}></MetaValueLabel>
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Drafts' />
                 <MetaValueLabel value={args.metaValue}></MetaValueLabel>
-              </ListItem>
+              </ListItemButton>
             </List>
           </Paper>
         </Grid>
@@ -200,20 +202,20 @@ const TemplateMetaValue = ({ secondary, ...args }) => {
         <Grid item xs={3}>
           <Paper>
             <List component='nav' aria-label='main mailbox folders'>
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Home' secondary={secondary} />
                 <MetaValueLabel value={args.metaValue}></MetaValueLabel>
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Inbox' secondary={secondary} />
                 <MetaValueLabel value={args.metaValue}></MetaValueLabel>
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Drafts' secondary={secondary} />
                 <MetaValueLabel value={args.metaValue}></MetaValueLabel>
-              </ListItem>
+              </ListItemButton>
             </List>
           </Paper>
         </Grid>
@@ -229,20 +231,20 @@ const TemplateSecondaryActions = ({ ...args }) => {
         <Grid item xs={3}>
           <Paper>
             <List component='nav' aria-label='main mailbox folders'>
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Home' />
                 <ExpandMore />
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Inbox' />
                 <ExpandMore />
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Drafts' />
                 <ExpandMore />
-              </ListItem>
+              </ListItemButton>
             </List>
           </Paper>
         </Grid>
@@ -250,26 +252,26 @@ const TemplateSecondaryActions = ({ ...args }) => {
         <Grid item xs={3}>
           <Paper>
             <List component='nav' aria-label='main mailbox folders'>
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Home' />
                 <ListItemSecondaryAction>
                   <Checkbox edge='end' />
                 </ListItemSecondaryAction>
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Inbox' />
                 <ListItemSecondaryAction>
                   <Checkbox edge='end' />
                 </ListItemSecondaryAction>
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Drafts' />
                 <ListItemSecondaryAction>
                   <Checkbox edge='end' />
                 </ListItemSecondaryAction>
-              </ListItem>
+              </ListItemButton>
             </List>
           </Paper>
         </Grid>
@@ -277,32 +279,32 @@ const TemplateSecondaryActions = ({ ...args }) => {
         <Grid item xs={3}>
           <Paper>
             <List component='nav' aria-label='main mailbox folders'>
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Home' />
                 <ListItemSecondaryAction>
                   <IconButton size='small' edge='end' aria-label='delete'>
                     <Delete />
                   </IconButton>
                 </ListItemSecondaryAction>
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Inbox' />
                 <ListItemSecondaryAction>
                   <IconButton size='small' edge='end' aria-label='delete'>
                     <Delete />
                   </IconButton>
                 </ListItemSecondaryAction>
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Drafts' />
                 <ListItemSecondaryAction>
                   <IconButton size='small' edge='end' aria-label='delete'>
                     <Delete />
                   </IconButton>
                 </ListItemSecondaryAction>
-              </ListItem>
+              </ListItemButton>
             </List>
           </Paper>
         </Grid>
@@ -310,26 +312,26 @@ const TemplateSecondaryActions = ({ ...args }) => {
         <Grid item xs={3}>
           <Paper>
             <List component='nav' aria-label='main mailbox folders'>
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Home' />
                 <ListItemSecondaryAction>
                   <Switch edge='end' />
                 </ListItemSecondaryAction>
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Inbox' />
                 <ListItemSecondaryAction>
                   <Switch edge='end' />
                 </ListItemSecondaryAction>
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Drafts' />
                 <ListItemSecondaryAction>
                   <Switch edge='end' />
                 </ListItemSecondaryAction>
-              </ListItem>
+              </ListItemButton>
             </List>
           </Paper>
         </Grid>
@@ -345,42 +347,42 @@ const TemplateNested = ({ ...args }) => {
         <Grid item xs={3}>
           <Paper>
             <List component='nav' aria-label='main mailbox folders'>
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Home' />
                 <ExpandLess />
-              </ListItem>
+              </ListItemButton>
               <Collapse in={true} timeout='auto' unmountOnExit>
                 <List component='div' disablePadding>
-                  <ListItem button>
+                  <ListItemButton>
                     <ListItemText primary='Sub item' />
-                  </ListItem>
+                  </ListItemButton>
                   <List component='div' disablePadding>
-                    <ListItem button>
+                    <ListItemButton>
                       <ListItemText primary='Sub item 2' />
-                    </ListItem>
+                    </ListItemButton>
                     <List component='div' disablePadding>
-                      <ListItem button>
+                      <ListItemButton>
                         <ListItemText primary='Sub item 3' />
-                      </ListItem>
+                      </ListItemButton>
                       <List component='div' disablePadding>
-                        <ListItem button>
+                        <ListItemButton>
                           <ListItemText primary='Sub item 4' />
-                        </ListItem>
+                        </ListItemButton>
                       </List>
                     </List>
                   </List>
                 </List>
               </Collapse>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Inbox' />
                 <ExpandMore />
-              </ListItem>
+              </ListItemButton>
               <Divider />
-              <ListItem button>
+              <ListItemButton>
                 <ListItemText primary='Drafts' />
                 <ExpandMore />
-              </ListItem>
+              </ListItemButton>
             </List>
           </Paper>
         </Grid>
@@ -389,8 +391,34 @@ const TemplateNested = ({ ...args }) => {
   );
 };
 
+const DocTemplate = () => {
+  return (
+    <DocContainer
+      severity='warning'
+      content='block'
+      action={
+        <Button
+          variant='outlined'
+          size='small'
+          color='inherit'
+          href='/?path=/docs/organisms-list-guide--page'
+        >
+          Guide
+        </Button>
+      }
+    >
+      In order <DocHighlight component='span'>ListItem</DocHighlight> to be interactive,
+      you need to use <DocHighlight component='span'>MenuItem</DocHighlight> component, or
+      use <DocHighlight component='span'>ListItemButton</DocHighlight> instead.
+      <Typography mt={2}>Note that {'<ListItem button />'} is deprecated.</Typography>
+    </DocContainer>
+  );
+};
+
 export const Playground = Template.bind({});
 
+export const Guide = DocTemplate.bind({});
+
 export const OneLine = Template.bind({});
 
 export const TwoLines = Template.bind({});
diff --git a/packages/react-ui/storybook/stories/organisms/ListItemGuide.stories.mdx b/packages/react-ui/storybook/stories/organisms/ListItemGuide.stories.mdx
new file mode 100644
index 000000000..14d8394fc
--- /dev/null
+++ b/packages/react-ui/storybook/stories/organisms/ListItemGuide.stories.mdx
@@ -0,0 +1,35 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title='Organisms/List/Guide' />
+
+# ListItem
+
+In order to be interactive, you need to use `MenuItem` component, or use `ListItemButton`instead.
+
+```
+<List>
+  <ListItem>
+    <ListItemButton>
+      <ListItemIcon>
+        <InboxIcon />
+      </ListItemIcon>
+      <ListItemText primary="Inbox" />
+    </ListItemButton>
+  </ListItem>
+<List>
+```
+
+```
+<MenuList>
+  <MenuItem>
+    <ListItemButton>
+      <ListItemIcon>
+        <InboxIcon />
+      </ListItemIcon>
+      <ListItemText primary="Inbox" />
+    </ListItemButton>
+  </MenuItem>
+<MenuList>
+```
+
+Note that `<ListItem button />` is deprecated.
diff --git a/packages/react-ui/storybook/stories/organisms/Menu.stories.js b/packages/react-ui/storybook/stories/organisms/Menu.stories.js
index 54913f5b8..53f82dda6 100644
--- a/packages/react-ui/storybook/stories/organisms/Menu.stories.js
+++ b/packages/react-ui/storybook/stories/organisms/Menu.stories.js
@@ -7,6 +7,8 @@ import {
   ContentPasteOutlined
 } from '@mui/icons-material';
 import Typography from '../../../src/components/atoms/Typography';
+import { DocContainer, DocHighlight } from '../../utils/storyStyles';
+import Button from '../../../src/components/atoms/Button';
 
 const options = {
   title: 'Organisms/Menu',
@@ -77,7 +79,33 @@ const Template = ({ label, ...args }) => {
   );
 };
 
+const DocTemplate = () => {
+  return (
+    <DocContainer
+      severity='warning'
+      content='block'
+      action={
+        <Button
+          variant='outlined'
+          size='small'
+          color='inherit'
+          href='/?path=/docs/organisms-list-guide--page'
+        >
+          Guide
+        </Button>
+      }
+    >
+      In order <DocHighlight component='span'>ListItem</DocHighlight> to be interactive,
+      you need to use <DocHighlight component='span'>MenuItem</DocHighlight> component, or
+      use <DocHighlight component='span'>ListItemButton</DocHighlight> instead.
+      <Typography mt={2}>Note that {'<ListItem button />'} is deprecated.</Typography>
+    </DocContainer>
+  );
+};
+
 const commonArgs = { label: 'Label', dense: false };
 
 export const Playground = Template.bind({});
 Playground.args = { ...commonArgs };
+
+export const Guide = DocTemplate.bind({});
diff --git a/packages/react-ui/storybook/utils/storyStyles.js b/packages/react-ui/storybook/utils/storyStyles.js
index 67c6d8eec..f65996750 100644
--- a/packages/react-ui/storybook/utils/storyStyles.js
+++ b/packages/react-ui/storybook/utils/storyStyles.js
@@ -48,18 +48,27 @@ export const FilledContainer = styled(Box)(({ theme }) => ({
 }));
 
 export const DocContainer = styled(Alert)(({ theme }) => ({
-  marginBottom: theme.spacing(3)
+  marginBottom: theme.spacing(3),
+
+  '& .MuiTypography-root': {
+    ...theme.typography.caption,
+    color: 'inherit'
+  }
 }));
 
-export const DocTextHighlight = styled(Typography)(({ theme }) => ({
-  display: 'inline',
-  fontWeight: theme.typography.fontWeightBold,
-  color: 'inherit'
+export const DocHighlight = styled(Typography)(({ theme }) => ({
+  '&.MuiTypography-root': {
+    display: 'inline',
+    color: 'inherit',
+    ...theme.typography.caption,
+    fontWeight: theme.typography.fontWeightBold
+  }
 }));
 
 export const DocLink = styled(Link)(({ theme }) => ({
   textDecoration: 'underline',
-  color: 'inherit'
+  color: 'inherit',
+  ...theme.typography.caption
 }));
 
 export const Label = styled(Typography)(({ theme }) => ({