[Website] Menu and Menu buttons docs

src/data/nav-items.yaml

@@ -124,12 +124,14 @@
       path: /components/loading/usage/
     - title: Modal
       path: /components/modal/usage/
+    - title: Menu
+      path: /components/menu/usage/
+    - title: Menu buttons
+      path: /components/menu-buttons/usage/
     - title: Notification
       path: /components/notification/usage/
     - title: Number input
       path: /components/number-input/usage/
-    - title: Overflow menu
-      path: /components/overflow-menu/usage/
     - title: Pagination
       path: /components/pagination/usage/
     - title: Popover

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

@@ -0,0 +1,93 @@
+---
+title: Menu buttons
+description:
+  Menu buttons, including menu buttons, combo buttons, and overflow menus, open
+  a menu with a list of interactive options.
+tabs: ['Usage', 'Style', 'Code', 'Accessibility']
+---
+
+import {
+  StructuredListWrapper,
+  StructuredListHead,
+  StructuredListBody,
+  StructuredListRow,
+  StructuredListInput,
+  StructuredListCell,
+  OrderedList,
+  ListItem,
+} from '@carbon/react';
+
+<PageDescription>
+
+No accessibility annotations are needed for overflow menus, but keep these
+considerations in mind if you are modifying Carbon or creating a custom
+component.
+
+</PageDescription>
+
+<InlineNotification>
+
+**Coming soon!** The accessibility information for the menu button and combo
+button is going to be updated soon.
+
+</InlineNotification>
+
+<AnchorLinks>
+
+<AnchorLink>What Carbon provides</AnchorLink>
+<AnchorLink>Development considerations</AnchorLink>
+
+</AnchorLinks>
+
+## What Carbon provides
+
+Carbon bakes keyboard operation into its components, improving the experience of
+blind users and others who operate via keyboard. Carbon also incorporates other
+accessibility considerations, some of which are described below.
+
+### Keyboard interaction
+
+Each overflow menu is in the tab order and is activated by `Space` or `Enter`.
+When the menu is open, the first item takes focus. Focus is moved between menu
+items with the `Up` and `Down` arrow keys. `Space` or `Enter` activates the item
+with focus (which causes focus to go somewhere else and the menu to close).
+`Esc` collapses the menu and puts focus onto the menu button.
+
+<Row>
+<Column colLg={8}>
+
+![example of overflow menu keyboard interaction](images/overflow-menu-accessibility-1.png)
+
+<Caption>
+  Overflow menus are reached by Tab. Space and Enter keys open the menu as well
+  as activating menu items with focus.
+</Caption>
+
+</Column>
+</Row>
+
+<Row>
+<Column colLg={8}>
+
+![illustration showing an open menu with the focus on the first item, and the arrow and Esc keys called out](images/overflow-menu-accessibility-2.png)
+
+<Caption>
+  When opened, the first item in the menu takes focus. Arrow keys move focus,
+  Esc closes the menu.
+</Caption>
+
+</Column>
+</Row>
+
+## Development considerations
+
+Keep these considerations in mind if you are modifying Carbon or creating a
+custom component.
+
+- Overflow menus are buttons with `aria-haspopup` set to "true".
+- The overflow menu is named with `aria-label`.
+- Each menu item is an `li` in a `ul`.
+- Each list item contains a button with `role="menuitem"` and `tabindex="-1"`.
+  See the
+  [ARIA authoring practices on menubutton](https://w3c.github.io/aria-practices/#menubutton)
+  for more considerations.

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

@@ -0,0 +1,181 @@
+---
+title: Menu buttons
+
+tabs: ['Usage', 'Style', 'Code', 'Accessibility']
+---
+
+<PageDescription>
+
+Preview the menu button, combo button, and overflow menu component with the
+React live demo. For detailed code usage documentation, see the Storybooks for
+each framework below.
+
+</PageDescription>
+
+## Documentation
+
+### Menu button
+
+<Row className="resource-card-group">
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+    subTitle="React"
+    href="https://react.carbondesignsystem.com/?path=/docs/components-menubutton--overview"
+    >
+
+<MdxIcon name="react" />
+
+  </ResourceCard>
+</Column>
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+      subTitle="Web Components coming soon"
+      disabled
+      href=""
+      >
+
+<MdxIcon name="webcomponents" />
+
+  </ResourceCard>
+</Column>
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+      subTitle="Angular (Community) coming soon"
+      disabled
+      href=""
+      >
+
+<MdxIcon name="angular" />
+
+  </ResourceCard>
+</Column>
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+      subTitle="Vue (Community) coming soon"
+      disabled
+      href=""
+      >
+
+<MdxIcon name="vue" />
+
+  </ResourceCard>
+</Column>
+</Row>
+
+### Combo button
+
+<Row className="resource-card-group">
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+    subTitle="React"
+    href="https://react.carbondesignsystem.com/?path=/docs/components-combobutton--overview"
+    >
+
+<MdxIcon name="react" />
+
+  </ResourceCard>
+</Column>
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+      subTitle="Web Components coming soon"
+      disabled
+      href=""
+      >
+
+<MdxIcon name="webcomponents" />
+
+  </ResourceCard>
+</Column>
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+      subTitle="Angular (Community) coming soon"
+      disabled
+      href=""
+      >
+
+<MdxIcon name="angular" />
+
+  </ResourceCard>
+</Column>
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+      subTitle="Vue (Community) coming soon"
+      disabled
+      href=""
+      >
+
+<MdxIcon name="vue" />
+
+  </ResourceCard>
+</Column>
+</Row>
+
+### Overflow menu
+
+<Row className="resource-card-group">
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+    subTitle="React"
+    href="https://react.carbondesignsystem.com/?path=/docs/components-overflowmenu--overview"
+    >
+
+<MdxIcon name="react" />
+
+  </ResourceCard>
+</Column>
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+      subTitle="Web Components coming soon"
+      disabled
+      href=""
+      >
+
+<MdxIcon name="webcomponents" />
+
+  </ResourceCard>
+</Column>
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+      subTitle="Angular (Community) coming soon"
+      disabled
+      href=""
+      >
+
+<MdxIcon name="angular" />
+
+  </ResourceCard>
+</Column>
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+      subTitle="Vue (Community) coming soon"
+      disabled
+      href=""
+      >
+
+<MdxIcon name="vue" />
+
+  </ResourceCard>
+</Column>
+</Row>
+
+## Live demo
+
+<StorybookDemo
+  themeSelector
+  url="https://react.carbondesignsystem.com"
+  short
+  variants={[
+    {
+      label: 'Menu button',
+      variant: 'components-menubutton--default',
+    },
+    {
+      label: 'Combo button',
+      variant: 'components-combobutton--default',
+    },
+    {
+      label: 'Overflow menu',
+      variant: 'components-overflowmenu--default',
+    },
+  ]}
+/>