Callout: fix role in examples, add some best practices wording (#22520)

microsoft · Apr 18, 2022 · 65926a5 · 65926a5
1 parent 66465d3
commit 65926a5
Show file tree

Hide file tree

Showing 4 changed files with 9 additions and 0 deletions.
diff --git a/packages/react-examples/src/react/Callout/Callout.Basic.Example.tsx b/packages/react-examples/src/react/Callout/Callout.Basic.Example.tsx
@@ -22,6 +22,7 @@ export const CalloutBasicExample: React.FunctionComponent = () => {
           className={styles.callout}
           ariaLabelledBy={labelId}
           ariaDescribedBy={descriptionId}
+          role="dialog"
           gapSpace={0}
           target={`#${buttonId}`}
           onDismiss={toggleIsCalloutVisible}

diff --git a/packages/react-examples/src/react/Callout/Callout.Cover.Example.tsx b/packages/react-examples/src/react/Callout/Callout.Cover.Example.tsx
@@ -15,6 +15,7 @@ export const CalloutCoverExample: React.FunctionComponent = () => {
         <Callout
           coverTarget
           ariaLabelledBy={labelId}
+          role="dialog"
           className={styles.callout}
           onDismiss={toggleIsCalloutVisible}
           target={`#${buttonId}`}

diff --git a/packages/react-examples/src/react/Callout/Callout.Directional.Example.tsx b/packages/react-examples/src/react/Callout/Callout.Directional.Example.tsx
@@ -72,6 +72,7 @@ export const CalloutDirectionalExample: React.FunctionComponent = () => {
         <Callout
           ariaLabelledBy={labelId}
           ariaDescribedBy={descriptionId}
+          role="dialog"
           className={styles.callout}
           gapSpace={gapSpace}
           target={`#${buttonId}`}

diff --git a/packages/react-examples/src/react/Callout/docs/CalloutBestPractices.md b/packages/react-examples/src/react/Callout/docs/CalloutBestPractices.md
@@ -15,3 +15,9 @@
 - Short sentences or sentence fragments are best.
 - Don't use obvious tip text or text that simply repeats what is already on the screen. Limit the information inside of a callout to supplemental information.
 - When additional context or a more advanced description is necessary, consider placing a link to "Learn more" at the bottom of the callout. When clicked, open the additional content in a new window or panel.
+
+### Accessibility
+
+If the callout is being used as a dialog (usually the case if you're moving focus within it when it is opened), then we recommend setting `role="dialog"` as demonstrated in our examples.
+
+Other possible roles include `alert` (shown in the "Non-focusable Callout with accessible text" example), `group` (a more generic non-dialog role), or `alertdialog` (shown in the "FocusTrapCallout variant" example).