menu update

src/pages/components/menu-buttons/style.mdx

@@ -91,8 +91,9 @@ guidelines.
 
 ## Sizes
 
-There are three [button](https://carbondesignsystem.com/components/button/usage)
-sizes: small, medium, and large.
+There are three
+[button](https://carbondesignsystem.com/components/button/style/#sizes) sizes:
+small, medium, and large.
 
 | Elements | Size        | Height (px/rem) |
 | -------- | ----------- | --------------- |

src/pages/components/menu-buttons/usage.mdx

@@ -18,10 +18,9 @@ v11.
 <AnchorLink>Formatting</AnchorLink>
 <AnchorLink>Content</AnchorLink>
 <AnchorLink>Universal behaviors</AnchorLink>
-<AnchorLink>Menu buttons</AnchorLink>
-<AnchorLink>Combo buttons</AnchorLink>
+<AnchorLink>Menu button</AnchorLink>
+<AnchorLink>Combo button</AnchorLink>
 <AnchorLink>Overflow menu</AnchorLink>
-<AnchorLink>Modifiers</AnchorLink>
 <AnchorLink>Related</AnchorLink>
 <AnchorLink>References</AnchorLink>
 <AnchorLink>Feedback</AnchorLink>
@@ -31,9 +30,9 @@ v11.
 ## Overview
 
 There are three variants of menu buttons (or menu triggers): menu button, combo
-button, and overflow menu button. Menu buttons comprise a button and a [menu](),
-which can be clicked to trigger an action or selected to initiate an action from
-a menu.
+button, and overflow menu button. Menu buttons comprise a button and a
+[menu](/components/menu/usage/), which can be clicked to trigger an action or
+selected to initiate an action from a menu.
 
 <Row>
 <Column colLg={12}>
@@ -115,9 +114,9 @@ A. Icon button <br /> C. Menu <br />
 #### Height
 
 Menu items come four sizes: extra small, small, medium, and large. See more
-about size specifications on the [style](/components/menu/style) tab. When using
-a menu button trigger, the height of the menu item (singular) reflects the size
-of the button being used.
+about size specifications on the [style](/components/menu/style/) tab. When
+using a menu button trigger, the height of the menu item (singular) reflects the
+size of the button being used.
 
 <InlineNotification>
 
@@ -165,15 +164,15 @@ By default, the [menu button](/components/menu-buttons/usage/#menu-button) and
 and the menu maintains a minimum width of 160px to prevent a narrow appearance.
 
 <Row>
-<Column colLg={12}>
+<Column colLg={8}>
 
-![Menu width](images/usage-menu-alignment-menu-buttons-default.png)
+![Menu width](images/usage-menu-width-menu-buttons-default.png)
+
+<Caption>Menu default width when labels are short </Caption>
 
 </Column>
 </Row>
 
-<Caption>Menu default width when labels are short </Caption>
-
 If the menu item labels become longer, the menu button and combo button remain
 the same size while the menu component can expand up to a maximum of 288px.
 Conversely, if the button labels become longer, the menu component should not
@@ -237,6 +236,14 @@ By default, combo button, menu button, or overflow button remains positioned at
 the top, to the left or right side of the menu when it is open, depending on the
 available space and layout.
 
+<Row>
+<Column colLg={8}>
+
+![Menu default alignments](images/usage-menu-alignment-menu-buttons-default.png)
+
+</Column>
+</Row>
+
 #### Alternatives
 
 Alternatively, open menus can be positioned at the bottom, to the left or right
@@ -324,42 +331,41 @@ Users can reveal the menu by:
 <Row>
 <Column colLg={8}>
 
-![Modal focus example](images/usage-menu-keyboard-menu-button.png)
+![Menu button interactions](images/usage-menu-keyboard-menu-button.png)
 
+<Caption>Mouse and keyboard interactions for menu button</Caption>
 </Column>
 </Row>
 
-<Caption>Mouse and keyboard interactions for menu button</Caption>
-
 #### Combo button
 
 Users can reveal the menu by:
 
-- Clicking anywhere on the field of the primary button or the icon button
+- Clicking anywhere on the field of the primary button or the icon button. If
+  clicking on the primary button, this will apply to certain elements, depending
+  on user interaction.
 - Or tabbing into the combo button which will focus on the primary button first
   then the icon button. Then, pressing the `Return` or `Enter` to trigger the
   action of the primary button or menu under icon button.
 
 <Row>
 <Column colLg={8}>
 
-![Modal focus example](images/usage-menu-mouse-combo-button.png)
+![Combo button mouse interaction](images/usage-menu-mouse-combo-button.png)
 
+<Caption>Mouse interactions for combo button</Caption>
 </Column>
 </Row>
 
-<Caption>Mouse interactions for combo button</Caption>
-
 <Row>
 <Column colLg={8}>
 
-![Modal focus example](images/usage-menu-keyboard-combo-button.png)
+![Combo button keyboard interaction](images/usage-menu-keyboard-combo-button.png)
 
+<Caption>Keyboard interactions for combo button</Caption>
 </Column>
 </Row>
 
-<Caption>Keyboard interactions for combo button</Caption>
-
 #### Overflow menu
 
 Users can reveal the overflow menu by:
@@ -370,13 +376,12 @@ Users can reveal the overflow menu by:
 <Row>
 <Column colLg={8}>
 
-![Modal focus example](images/usage-menu-mouse-keyboard-overflow-menu.png)
+![Overflow menu mouse and keyboard interactions](images/usage-menu-mouse-keyboard-overflow-menu.png)
 
+<Caption>Keyboard interactions for overflow menu</Caption>
 </Column>
 </Row>
 
-<Caption>Keyboard interactions for overflow menu</Caption>
-
 ## Menu button
 
 Menu buttons group actions that share the same level of importance. The icon
@@ -437,7 +442,7 @@ action, all of which are presented as choices within the menu button.
 </Column>
 </Row>
 
-### Distinct actions applied to the same object or page
+#### Distinct actions applied to the same object or page
 
 In many cases, actions on a page may not use the same verb or have a shared
 label for the menu button. When grouped actions remain distinct, consider
@@ -448,9 +453,9 @@ labeling the menu button as 'Actions' to encompass all available choices.
 
 ![Distinct actions applied to the same object or page](images/usage-menu-button-5.png)
 
+<Caption>Example shows the menu button with possible actions that could influence the data within tab contents</Caption>
 </Column>
 </Row>
-<Caption>Example shows the menu button with possible actions that could influence the data within tab contents</Caption>
 
 ## Combo button
 
@@ -488,13 +493,12 @@ take.
 
 ![Choose a default action](images/usage-menu-combo-button-2.png)
 
-</Column>
-</Row>
-
 <Caption>
   Example shows that users mostly choose to save records, while less common
   options are hidden as extra actions.
 </Caption>
+</Column>
+</Row>
 
 #### Reduce visual complexity on a page
 
@@ -507,13 +511,12 @@ conceptual understanding of the site information structure.
 
 ![Reduce visual complexity on a page](images/usage-menu-combo-button-3.png)
 
-</Column>
-</Row>
-
 <Caption>
   Example shows that many actions (ghost buttons) applying to the same data can
   be replaced by the combo button.
 </Caption>
+</Column>
+</Row>
 
 ## Overflow menu
 

src/pages/components/menu/accessibility.mdx

@@ -6,6 +6,6 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 
 <InlineNotification>
 
-**Coming soon!** This page is a work of progress.
+**Coming soon!** This page is a work in progress.
 
 </InlineNotification>

src/pages/components/menu/style.mdx

@@ -7,14 +7,11 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 
 ### Default state
 
-Refer to the [button](/components/button/style) for primary and secondary button
-styling in the transactional modal.
-
 | Elements      | Property         | Color token                |
 | ------------- | ---------------- | -------------------------- |
 | Menu option   | background-color | `$layer` \*                |
 |               | text-color       | `$text-secondary`          |
-|               | border-top       | `$border-subtle`           |
+|               | border-top       | `$border-subtle` \*        |
 | Caret icon    | svg              | `$icon-secondary`          |
 | Shortcut icon | svg              | `$icon-secondary`          |
 | Container     | box-shadow       | 0 2px 6px 0 rgba(0,0,0,.2) |

src/pages/components/menu/usage.mdx

@@ -43,18 +43,6 @@ menu component effectively.
 </Column>
 </Row>
 
-<StorybookDemo
-  themeSelector
-  url="https://react.carbondesignsystem.com"
-  short
-  variants={[
-    {
-      label: 'Menu',
-      variant: 'components-menu--default',
-    },
-  ]}
-/>
-
 ### When to use
 
 #### Declutter interface
@@ -91,6 +79,18 @@ When many or complex inputs are used collectively, use a
 [popover](https://www.carbondesignsystem.com/components/popover/usage) instead
 of a menu.
 
+<StorybookDemo
+  themeSelector
+  url="https://react.carbondesignsystem.com"
+  short
+  variants={[
+    {
+      label: 'Menu',
+      variant: 'components-menu--default',
+    },
+  ]}
+/>
+
 ## Formatting
 
 ### Anatomy
@@ -186,11 +186,10 @@ maintains a minimum width of 160px to prevent a narrow appearance.
 
 ![Menu width](images/usage-menu-alignment-menu-buttons-default.png)
 
+<Caption>Menu default width when labels are short </Caption>
 </Column>
 </Row>
 
-<Caption>Menu default width when labels are short </Caption>
-
 If the menu item labels become longer, the menu button and combo button remain
 the same size while the menu component can expand up to a maximum of 288px.
 Conversely, if the button labels become longer, the menu component should not
@@ -254,6 +253,14 @@ By default, combo button, menu button, or overflow button remains positioned at
 the top, to the left or right side of the menu when it is open, depending on the
 available space and layout.
 
+<Row>
+<Column colLg={8}>
+
+![Menu default alignments](images/usage-menu-alignment-menu-buttons-default.png)
+
+</Column>
+</Row>
+
 #### Alternatives
 
 Alternatively, open menus can be positioned at the bottom, to the left or right
@@ -313,11 +320,10 @@ truncating long menu items, use a tooltip on hover to reveal the full text.
 
 ![An overflow example for menu items](images/usage-menu-overflow-content.png)
 
+<Caption>Tooltip helps clarify the truncated text</Caption>
 </Column>
 </Row>
 
-<Caption>Tooltip helps clarify the truncated text</Caption>
-
 #### Ordering and grouping
 
 To aid discoverability, arrange menu items in a meaningful sequence that aligns
@@ -332,12 +338,11 @@ into sections, separated by divider lines.
 
 ![Ordering and grouping](images/usage-menu-ordering.png)
 
-</Column>
-</Row>
-
 <Caption>
   Example shows how menu items are grouped into meaningful sections.
 </Caption>
+</Column>
+</Row>
 
 #### Number of items within a menu
 
@@ -405,8 +410,7 @@ For further content guidance, see Carbon's
 
 Menu items have seven main progress states– enabled, hover, focus, focus and
 hover, danger hover, danger hover and focus, and disabled. Learn more about
-states on the [style](https://carbondesignsystem.com/components/menu/style/)
-tab.
+states on the [style](/components/menu/style/) tab.
 
 | Modal size             | Height (px / rem)                                                                                                                                                                                                                                         |
 | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -435,11 +439,10 @@ area, users can:
 
 ![Mouse interactions on menus](images/usage-interactions-mouse.png)
 
+<Caption>Mouse interactions on menu</Caption>
 </Column>
 </Row>
 
-<Caption>Mouse interactions on menu</Caption>
-
 #### Keyboard
 
 Once the menu opens by pressing `Return` or `Enter` on the menu trigger, users