menu update

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

@@ -0,0 +1,125 @@
+---
+title: Modal
+description:
+  Modals focus the user’s attention exclusively on one task or piece of
+  information via a window that sits on top of the page content.
+tabs: ['Usage', 'Style', 'Code', 'Accessibility']
+---
+
+import {
+  StructuredListWrapper,
+  StructuredListHead,
+  StructuredListBody,
+  StructuredListRow,
+  StructuredListInput,
+  StructuredListCell,
+  OrderedList,
+  ListItem,
+} from '@carbon/react';
+
+<PageDescription>
+
+Design annotations are needed for specific instances shown below, but for the
+standard modal dialog component, Carbon already incorporates accessibility.
+
+</PageDescription>
+
+<AnchorLinks>
+  <AnchorLink>What Carbon provides</AnchorLink>
+  <AnchorLink>Design recommendations</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 the keyboard. Carbon incorporates many
+other accessibility considerations, some of which are described below.
+
+### Keyboard interactions
+
+Modal dialogs take focus on appearance, and the tab order is constrained to the
+modal’s controls until the modal is closed by choosing one of the buttons with
+`Enter` or `Space`, or is dismissed by pressing `Esc`.
+
+<Row>
+<Column colLg={8}>
+
+![illustration showing tab ring constrained within a modal with two buttons](images/modal-accessibility-1.png)
+
+<Caption>
+  Keyboard navigation is constrained to the dialog. Tab cycles through the
+  components that take focus.
+</Caption>
+
+</Column>
+</Row>
+
+<Row>
+<Column colLg={8}>
+
+![Esc closes a modal, while Space and Enter keys activate buttons](images/modal-accessibility-2.png)
+
+<Caption>
+  The dialog is resolved by the user pressing Esc or activating a button.
+</Caption>
+
+</Column>
+</Row>
+
+### Focus handling
+
+When the dialog appears, the first item that gets focus depends on the type of
+dialog. Passive dialogs only contain a close button (X), so that takes focus.
+For dialogs which prompt for confirmation or user decision, the primary button
+takes focus (regardless of number of buttons). For destructive interactions, the
+“cancel” button takes focus, not the red danger/delete button. The tab order
+should proceed left and down from whichever item has focus then wrap back to the
+close button (X).
+
+<Row>
+<Column colLg={8}>
+
+![initial focus in the dialog varies across four types of modals](images/modal-accessibility-3.png)
+
+<Caption>The first item with focus varies depending on dialog type.</Caption>
+
+</Column>
+</Row>
+
+## Design recommendations
+
+### Designate the input that takes focus in a transactional
+
+The only time the starting focus would not be on a button is where a dialog
+contains input fields. For such transactional dialogs, designers should annotate
+that the first input field should receive focus. Note that text links are not
+considered a user input in this context.
+
+<DoDontRow>
+  <DoDont type="do" caption="Annotate the starting input that should take focus on a transactional dialog.">
+
+![annotation on input says 'focus lands here when modal opens'](images/modal-accessibility-4-do.png)
+
+  </DoDont>
+
+  <DoDont type="dont" caption="Do not give a link focus when a modal opens.">
+
+![annotation on link says 'focus lands here when modal opens'](images/modal-accessibility-4-dont.png)
+
+  </DoDont>
+</DoDontRow>
+
+## Development considerations
+
+Keep these considerations in mind if you are modifying Carbon or creating a
+custom component.
+
+- Carbon assigns the container a role of "dialog" and sets `aria-modal` to
+  `"true"`.
+- The dialog is labelled via `aria-label`, using the same string used for the
+  modal’s title; `aria-labelledby` could also be used to assign the title’s
+  string.
+- See the modal pattern in the
+  [ARIA authoring practices](https://w3c.github.io/aria-practices/#dialog_modal)
+  for more considerations.

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

@@ -0,0 +1,127 @@
+---
+title: Menu buttons
+tabs: ['Usage', 'Style', 'Code', 'Accessibility']
+---
+
+## Color
+
+Enabled and interactive states of menu buttons follow the
+[button style](https://carbondesignsystem.com/components/button/style)
+guidelines. Menu buttons can use primary, tertiary, or ghost buttons. Combo
+buttons can only use a primary button. Overflow menu can only use a ghost
+button.
+
+The menu used in menu buttons should follow the [menu style].
+
+### Menu button
+
+<Row>
+<Column colLg={8}>
+
+![Menu button variants](images/style-menu-buttons.png)
+
+</Column>
+</Row>
+
+<Caption>Example of menu button using three different types of buttons</Caption>
+
+### Combo button
+
+<Row>
+<Column colLg={8}>
+
+![Combo button](images/style-combo-button.png)
+
+</Column>
+</Row>
+
+<Caption>Example of a combo button using a primary button</Caption>
+
+### Overflow menu
+
+<Row>
+<Column colLg={8}>
+
+![Overflow menu](images/style-overflow-menu.png)
+
+</Column>
+</Row>
+
+<Caption>
+  Overflow menu appears as a ghost button when closed and once it opens the
+  color changes to the correct $layer color token to match the menu.
+</Caption>
+
+## Typography
+
+| Element          | Font-size (px/rem) | Font-weight   | Type token         |
+| ---------------- | ------------------ | ------------- | ------------------ |
+| Button text      | 14 / 0.875         | Regular / 400 | `$body-compact-01` |
+| Menu option text | 14 / 0.875         | Regular / 400 | `$body-compact-01` |
+
+## Structure
+
+The structure of menu buttons should follow the
+[button style](https://carbondesignsystem.com/components/button/style)
+guidelines.
+
+### Menu button
+
+<div className="image--fixed">
+
+![Menu button structure](images/style-structure-menu-button.png)
+
+</div>
+
+<Caption>
+  Menu button in default width (left) and menu button in fluid width (right)
+</Caption>
+
+### Combo button
+
+<div className="image--fixed">
+
+![Combo button structure](images/style-structure-combo-button.png)
+
+</div>
+
+<Caption>
+  Combo button in default width (left) and menu button in fluid width (right)
+</Caption>
+
+<div className="image--fixed">
+
+![Submenu structure](images/style-menu-structure-submenus.png)
+
+</div>
+
+<Caption>Structure and spacing measurements for submenu</Caption>
+
+<div className="image--fixed">
+
+![Menu option item structure](images/style-menu-structure-action-items.png)
+
+</div>
+
+<Caption>
+  Structure and spacing measurements for individual menu option items
+</Caption>
+
+## Sizes
+
+There are three [button](https://carbondesignsystem.com/components/button/usage)
+sizes: small, medium, and large.
+
+| Elements | Size        | Height (px/rem) |
+| -------- | ----------- | --------------- |
+| Button   | Small (sm)  | 32/2            |
+|          | Medium (md) | 40/2.5          |
+|          | Large (lg)  | 48/3            |
+
+<Row>
+<Column colLg={8}>
+
+![Modal sizes](images/style-menu-sizes.png)
+
+</Column>
+</Row>