create new a11y.mdx

src/pages/components/popover/accessibility.mdx

@@ -0,0 +1,80 @@
+---
+title: Popover
+description:
+  No accessibility annotations are needed for popover, but keep these
+  considerations in mind if you are modifying Carbon or creating a custom
+  component.
+tabs: ['Usage', 'Style', 'Code', 'Accessibility']
+---
+
+import A11yStatus from 'components/A11yStatus';
+
+import { Popover } from '@carbon/react';
+
+<PageDescription>
+
+No accessibility annotations are needed for popover, but keep these
+considerations in mind if you are modifying Carbon or creating a custom
+component.
+
+</PageDescription>
+
+<AnchorLinks>
+  <AnchorLink>What Carbon provides</AnchorLink>
+  <AnchorLink>Development considerations</AnchorLink>
+</AnchorLinks>
+
+<A11yStatus layout="table" components="Popover" />
+
+## 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
+
+Popovers use an icon button for the trigger. These buttons are in the tab order
+and are activated by pressing `Enter` or `Space`. The activation toggles the
+popover open and closed, and focus remains on the trigger.
+
+When the popover contains interactive elements, pressing `Tab` will move focus
+to the first component in the popover. When the popover only has non-interactive
+text, or when the focus is on the last component in the popover, pressing `Tab`
+will close the popover and move focus to the next tab stop on the page.
+
+<Row>
+<Column colLg={12}>
+
+![The icon button that triggers the popover is in the page tab order, as are interactive elements inside an open popover.](images/popover-a11y-1.png)
+
+<Caption>
+  The icon button that triggers the popover is in the page tab order, as are
+  interactive elements inside an open popover.
+</Caption>
+
+</Column>
+</Row>
+
+Popovers appear when the icon button is activated and disappear by activating
+the icon button again, pressing `Esc`, or tabbing away from the popover.
+
+<Row>
+<Column colLg={12}>
+
+![Use Space or Enter to toggle the popover open and close, and use Esc or tab on the last interactive element in the popover to dismiss it.](images/popover-a11y-2.png)
+
+<Caption>
+  Use Space or Enter to toggle the popover open and close, and use Esc or tab on
+  the last interactive element in the popover to dismiss it.
+</Caption>
+
+</Column>
+</Row>
+
+## Development considerations
+
+Keep these considerations in mind if you are modifying Carbon or creating a
+custom component. — The icon button has an aria-label that defines what the icon
+depicts. — The button uses aria-expanded to set popover visibility and
+aria-controls to handle navigation to the content.