diff --git a/src/pages/components/menu-buttons/images/style-structure-combo-button.png b/src/pages/components/menu-buttons/images/style-structure-combo-button.png
index aedcb125ba3..f2cad6e961b 100644
Binary files a/src/pages/components/menu-buttons/images/style-structure-combo-button.png and b/src/pages/components/menu-buttons/images/style-structure-combo-button.png differ
diff --git a/src/pages/components/menu-buttons/images/style-structure-menu-button.png b/src/pages/components/menu-buttons/images/style-structure-menu-button.png
index 390395a9793..c1a67acd6b1 100644
Binary files a/src/pages/components/menu-buttons/images/style-structure-menu-button.png and b/src/pages/components/menu-buttons/images/style-structure-menu-button.png differ
diff --git a/src/pages/components/menu-buttons/images/usage-menu-alignment-menu-buttons-default.png b/src/pages/components/menu-buttons/images/usage-menu-alignment-menu-buttons-default.png
index c9b8e3e3033..92b384fb00e 100644
Binary files a/src/pages/components/menu-buttons/images/usage-menu-alignment-menu-buttons-default.png and b/src/pages/components/menu-buttons/images/usage-menu-alignment-menu-buttons-default.png differ
diff --git a/src/pages/components/menu-buttons/images/usage-menu-button-4.png b/src/pages/components/menu-buttons/images/usage-menu-button-4.png
index 773b2729e5e..bac86731c79 100644
Binary files a/src/pages/components/menu-buttons/images/usage-menu-button-4.png and b/src/pages/components/menu-buttons/images/usage-menu-button-4.png differ
diff --git a/src/pages/components/menu-buttons/images/usage-menu-ghost-button-width-don.png b/src/pages/components/menu-buttons/images/usage-menu-ghost-button-width-don.png
new file mode 100644
index 00000000000..b39dafea7f8
Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-ghost-button-width-don.png differ
diff --git a/src/pages/components/menu-buttons/images/usage-menu-ghost-button-width-dont.png b/src/pages/components/menu-buttons/images/usage-menu-ghost-button-width-dont.png
index b39dafea7f8..baa8b1380af 100644
Binary files a/src/pages/components/menu-buttons/images/usage-menu-ghost-button-width-dont.png and b/src/pages/components/menu-buttons/images/usage-menu-ghost-button-width-dont.png differ
diff --git a/src/pages/components/menu-buttons/images/usage-menu-width-menu-buttons-default.png b/src/pages/components/menu-buttons/images/usage-menu-width-menu-buttons-default.png
new file mode 100644
index 00000000000..ea1896185d3
Binary files /dev/null and b/src/pages/components/menu-buttons/images/usage-menu-width-menu-buttons-default.png differ
diff --git a/src/pages/components/menu-buttons/style.mdx b/src/pages/components/menu-buttons/style.mdx
index d08de480c56..d75b3e929f3 100644
--- a/src/pages/components/menu-buttons/style.mdx
+++ b/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) |
| -------- | ----------- | --------------- |
diff --git a/src/pages/components/menu-buttons/usage.mdx b/src/pages/components/menu-buttons/usage.mdx
index cfc6c7c000b..fa43597a179 100644
--- a/src/pages/components/menu-buttons/usage.mdx
+++ b/src/pages/components/menu-buttons/usage.mdx
@@ -18,10 +18,9 @@ v11.
Formatting
Content
Universal behaviors
-Menu buttons
-Combo buttons
+Menu button
+Combo button
Overflow menu
-Modifiers
Related
References
Feedback
@@ -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.
@@ -115,9 +114,9 @@ A. Icon button
C. Menu
#### 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.
@@ -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.
-
+
-![Menu width](images/usage-menu-alignment-menu-buttons-default.png)
+![Menu width](images/usage-menu-width-menu-buttons-default.png)
+
+Menu default width when labels are short
-Menu default width when labels are short
-
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.
+
+
+
+![Menu default alignments](images/usage-menu-alignment-menu-buttons-default.png)
+
+
+
+
#### Alternatives
Alternatively, open menus can be positioned at the bottom, to the left or right
@@ -324,18 +331,19 @@ Users can reveal the menu by:
-![Modal focus example](images/usage-menu-keyboard-menu-button.png)
+![Menu button interactions](images/usage-menu-keyboard-menu-button.png)
+Mouse and keyboard interactions for menu button
-Mouse and keyboard interactions for menu button
-
#### 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.
@@ -343,23 +351,21 @@ Users can reveal the menu by:
-![Modal focus example](images/usage-menu-mouse-combo-button.png)
+![Combo button mouse interaction](images/usage-menu-mouse-combo-button.png)
+Mouse interactions for combo button
-Mouse interactions for combo button
-
-![Modal focus example](images/usage-menu-keyboard-combo-button.png)
+![Combo button keyboard interaction](images/usage-menu-keyboard-combo-button.png)
+Keyboard interactions for combo button
-Keyboard interactions for combo button
-
#### Overflow menu
Users can reveal the overflow menu by:
@@ -370,13 +376,12 @@ Users can reveal the overflow menu by:
-![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)
+Keyboard interactions for overflow menu
-Keyboard interactions for overflow menu
-
## 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.
-### 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)
+
Example shows the menu button with possible actions that could influence the data within tab contents
-Example shows the menu button with possible actions that could influence the data within tab contents
## Combo button
@@ -488,13 +493,12 @@ take.
![Choose a default action](images/usage-menu-combo-button-2.png)
-
-
-
Example shows that users mostly choose to save records, while less common
options are hidden as extra actions.
+
+
#### 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)
-
-
-
Example shows that many actions (ghost buttons) applying to the same data can
be replaced by the combo button.
+
+
## Overflow menu
diff --git a/src/pages/components/menu/accessibility.mdx b/src/pages/components/menu/accessibility.mdx
index d9d6627bac7..a214b1d32f0 100644
--- a/src/pages/components/menu/accessibility.mdx
+++ b/src/pages/components/menu/accessibility.mdx
@@ -6,6 +6,6 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
-**Coming soon!** This page is a work of progress.
+**Coming soon!** This page is a work in progress.
diff --git a/src/pages/components/menu/images/usage-menu-alignment-menu-buttons-default.png b/src/pages/components/menu/images/usage-menu-alignment-menu-buttons-default.png
index c9b8e3e3033..92b384fb00e 100644
Binary files a/src/pages/components/menu/images/usage-menu-alignment-menu-buttons-default.png and b/src/pages/components/menu/images/usage-menu-alignment-menu-buttons-default.png differ
diff --git a/src/pages/components/menu/style.mdx b/src/pages/components/menu/style.mdx
index af4c34a151e..69afccf7f7d 100644
--- a/src/pages/components/menu/style.mdx
+++ b/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) |
diff --git a/src/pages/components/menu/usage.mdx b/src/pages/components/menu/usage.mdx
index 27e94619324..66d0ee9ddea 100644
--- a/src/pages/components/menu/usage.mdx
+++ b/src/pages/components/menu/usage.mdx
@@ -43,18 +43,6 @@ menu component effectively.
-
-
### 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.
+
+
## 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)
+Menu default width when labels are short
-Menu default width when labels are short
-
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.
+
+
+
+![Menu default alignments](images/usage-menu-alignment-menu-buttons-default.png)
+
+
+
+
#### 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)
+Tooltip helps clarify the truncated text
-Tooltip helps clarify the truncated text
-
#### 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)
-
-
-
Example shows how menu items are grouped into meaningful sections.
+
+
#### 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)
+Mouse interactions on menu
-Mouse interactions on menu
-
#### Keyboard
Once the menu opens by pressing `Return` or `Enter` on the menu trigger, users