From 1c1387d2ad232f770959d297a2eb65f853164cdb Mon Sep 17 00:00:00 2001
From: 1Copenut <trevor.pierce@elastic.co>
Date: Tue, 13 Feb 2024 15:25:35 -0600
Subject: [PATCH] [DOCS] Added guidance for EuiTooltip, EuiPopover

* Added a11y guidance to EuiTooltip.
* Added a11y guidance to EuiPopover.
---
 src-docs/src/views/popover/popover_example.js | 35 ++++++++++++++---
 .../src/views/tool_tip/tool_tip_example.js    | 38 ++++++++++---------
 2 files changed, 50 insertions(+), 23 deletions(-)

diff --git a/src-docs/src/views/popover/popover_example.js b/src-docs/src/views/popover/popover_example.js
index 356288d8bbc..f8f532dbcd8 100644
--- a/src-docs/src/views/popover/popover_example.js
+++ b/src-docs/src/views/popover/popover_example.js
@@ -10,6 +10,7 @@ import {
   EuiPopoverTitle,
   EuiPopoverFooter,
   EuiCallOut,
+  EuiText,
 } from '../../../../src/components';
 
 import { EuiPopoverPanelProps } from './props';
@@ -157,6 +158,35 @@ const inputPopoverSnippet = `<EuiInputPopover
 
 export const PopoverExample = {
   title: 'Popover',
+  intro: (
+    <EuiText>
+      <p>
+        Use the <strong>EuiPopover</strong> component to hide controls or
+        options behind a clickable element. A popover is temporary so keep tasks
+        simple and narrowly focused.
+      </p>
+
+      <EuiCallOut
+        iconType="accessibility"
+        color="warning"
+        title="Popovers have three accessibility requirements:"
+      >
+        <>
+          <ul>
+            <li>
+              Popover triggers <strong>must</strong> be anchored to elements
+              that accept keyboard focus.
+            </li>
+            <li>
+              Popovers can contain interactive elements. They{' '}
+              <strong>must</strong> be controlled by a click handler.
+            </li>
+            <li>Popovers must not be activated by hover or focus events.</li>
+          </ul>
+        </>
+      </EuiCallOut>
+    </EuiText>
+  ),
   sections: [
     {
       source: [
@@ -167,11 +197,6 @@ export const PopoverExample = {
       ],
       text: (
         <>
-          <p>
-            Use the <strong>EuiPopover</strong> component to hide controls or
-            options behind a clickable element. A popover is temporary so keep
-            tasks simple and narrowly focused.
-          </p>
           <p>
             While the visibility of the popover is maintained by the consuming
             application, popovers will automatically close when clicking outside
diff --git a/src-docs/src/views/tool_tip/tool_tip_example.js b/src-docs/src/views/tool_tip/tool_tip_example.js
index 9415195fee4..e2bcaff6d58 100644
--- a/src-docs/src/views/tool_tip/tool_tip_example.js
+++ b/src-docs/src/views/tool_tip/tool_tip_example.js
@@ -66,13 +66,26 @@ export const ToolTipExample = {
       <EuiCallOut
         iconType="accessibility"
         color="warning"
-        title={
-          <>
-            Putting anything other than plain text in a tooltip is lost on
-            screen readers.
-          </>
-        }
-      />
+        title="Tooltips have three accessibilty requirements:"
+      >
+        <>
+          <ul>
+            <li>
+              Tooltips <strong>must</strong> be anchored to elements that accept
+              keyboard focus.
+            </li>
+            <li>
+              Put only plain text in tooltips so the content is accessible to
+              keyboard and screen reader users.
+            </li>
+            <li>
+              {' '}
+              Do not add links, buttons, or other interactive content inside
+              tooltips.
+            </li>
+          </ul>
+        </>
+      </EuiCallOut>
     </EuiText>
   ),
   sections: [
@@ -87,17 +100,6 @@ export const ToolTipExample = {
             will change it if the tooltip gets too close to the edge of the
             screen.
           </p>
-
-          <EuiCallOut
-            iconType="accessibility"
-            color="warning"
-            title={
-              <>
-                Anchoring a tooltip to a non-interactive element makes it
-                difficult for keyboard-only and screen reader users to read.
-              </>
-            }
-          />
         </>
       ),
       source: [