From c53ecdff5442cf4ac5da0d1e2ba45871ab662855 Mon Sep 17 00:00:00 2001
From: Kate Higa <16447748+khiga8@users.noreply.github.com>
Date: Fri, 11 Feb 2022 10:27:13 -0800
Subject: [PATCH] Deprecate CSS tooltip (#1936)

* deprecate tooltip css

* update examples

* Create wise-cameras-leave.md

Co-authored-by: Jon Rohan <yes@jonrohan.codes>
---
 .changeset/wise-cameras-leave.md    |  5 ++
 docs/content/components/tooltips.md | 87 +++++++++++++++--------------
 2 files changed, 50 insertions(+), 42 deletions(-)
 create mode 100644 .changeset/wise-cameras-leave.md

diff --git a/.changeset/wise-cameras-leave.md b/.changeset/wise-cameras-leave.md
new file mode 100644
index 00000000..3fed3043
--- /dev/null
+++ b/.changeset/wise-cameras-leave.md
@@ -0,0 +1,5 @@
+---
+"@primer/css": minor
+---
+
+Deprecating `.tooltipped` CSS classes
diff --git a/docs/content/components/tooltips.md b/docs/content/components/tooltips.md
index edc76650..227553eb 100644
--- a/docs/content/components/tooltips.md
+++ b/docs/content/components/tooltips.md
@@ -1,15 +1,16 @@
 ---
 title: Tooltips
 path: components/tooltips
-status: Stable
+status: Deprecated
 source: 'https://github.com/primer/css/tree/main/src/tooltips'
 bundle: tooltips
 ---
 
+<Note>
+  Please note that the `.tooltipped` component is **deprecated**.
+</Note>
 
-Add tooltips built entirely in CSS to nearly any element.
-
-
+Add tooltips built entirely in CSS to appropriate elements.
 
 ## Implementation and accessibility
 
@@ -17,43 +18,45 @@ Tooltips as a UI pattern should be our last resort for conveying information bec
 
 Before adding a tooltip, please consider: Is this information essential and necessary* Can the UI be made clearer? Can the information be shown on the page by default?
 
-**Attention**: we use `aria-label` for tooltip contents, because it is crucial that they are accessible to screen reader users. However, `aria-label` **replaces** the text content of an element in screen readers, so only use `.tooltipped` on elements with no existing text content, or consider using `title` for supplemental information.
+### Attention
 
-**Note:** Tooltip classes will conflict with Octicon styles, and as such, must be applied to the parent element instead of the icon.
+- **Never** use tooltips on static elements. They should only be used on interactive elements, because users cannot tab-focus into static elements, which may make the content inaccessible for keyboard-only users and screen readers.
+- we use `aria-label` for tooltip contents, because it is crucial that they are accessible to screen reader users. However, `aria-label` **replaces** the text content of an element in screen readers, so only use `.tooltipped` on elements with no existing text content such as an icon-only button.
+- Tooltip classes will conflict with Octicon styles, and as such, must be applied to the parent element instead of the icon.
 
 ## Tooltip direction
 Specify the direction of a tooltip with north, south, east, and west directions:
 
 ```html live
 <div class="d-flex flex-justify-center pt-4">
-  <span class="tooltipped tooltipped-nw m-2 p-2 border" aria-label="This is the tooltip on the North West side.">
+  <button type="button" class="tooltipped tooltipped-nw m-2 p-2 border" aria-label="This is the tooltip on the North West side.">
     .tooltipped-nw
-  </span>
-  <span class="tooltipped tooltipped-n m-2 p-2 border" aria-label="This is the tooltip on the North side.">
+  </button>
+  <button type="button" class="tooltipped tooltipped-n m-2 p-2 border" aria-label="This is the tooltip on the North side.">
     .tooltipped-n
-  </span>
-  <span class="tooltipped tooltipped-ne m-2 p-2 border" aria-label="This is the tooltip on the North East side.">
+  </button>
+  <button type="button" class="tooltipped tooltipped-ne m-2 p-2 border" aria-label="This is the tooltip on the North East side.">
     .tooltipped-ne
-  </span>
+  </button>
 </div>
 <div class="d-flex flex-justify-center">
-  <span class="tooltipped tooltipped-w m-2 p-2 border" aria-label="This is the tooltip on the West side.">
+  <button type="button" class="tooltipped tooltipped-w m-2 p-2 border" aria-label="This is the tooltip on the West side.">
     .tooltipped-w
-  </span>
-  <span class="tooltipped tooltipped-e m-2 p-2 border" aria-label="This is the tooltip on the East side.">
+  </button>
+  <button type="button" class="tooltipped tooltipped-e m-2 p-2 border" aria-label="This is the tooltip on the East side.">
     .tooltipped-e
-  </span>
+  </button>
 </div>
 <div class="d-flex flex-justify-center pb-4">
-  <span class="tooltipped tooltipped-sw m-2 p-2 border" aria-label="This is the tooltip on the South West side.">
+  <button type="button" class="tooltipped tooltipped-sw m-2 p-2 border" aria-label="This is the tooltip on the South West side.">
     .tooltipped-sw
-  </span>
-  <span class="tooltipped tooltipped-s m-2 p-2 border" aria-label="This is the tooltip on the South side.">
+  </button>
+  <button type="button" class="tooltipped tooltipped-s m-2 p-2 border" aria-label="This is the tooltip on the South side.">
     .tooltipped-s
-  </span>
-  <span class="tooltipped tooltipped-se m-2 p-2 border" aria-label="This is the tooltip on the South East side.">
+  </button>
+  <button type="button" class="tooltipped tooltipped-se m-2 p-2 border" aria-label="This is the tooltip on the South East side.">
     .tooltipped-se
-  </span>
+  </button>
 </div>
 ```
 
@@ -62,36 +65,36 @@ Align tooltips to the left or right of an element, combined with a directional c
 
 ```html live
 <div class="d-flex flex-justify-center pt-4">
-  <span class="tooltipped tooltipped-nw tooltipped-align-right-1 m-2 p-2 border" aria-label="Tooltipped NW and aligned right.">
+  <button type="button" class="tooltipped tooltipped-nw tooltipped-align-right-1 m-2 p-2 border" aria-label="Tooltipped NW and aligned right.">
     .tooltipped-nw .tooltipped-align-right-1
-  </span>
-  <span class="tooltipped tooltipped-ne tooltipped-align-left-1 m-2 p-2 border" aria-label="Tooltipped NE and aligned left.">
+  </button>
+  <button type="button" class="tooltipped tooltipped-ne tooltipped-align-left-1 m-2 p-2 border" aria-label="Tooltipped NE and aligned left.">
     .tooltipped-ne .tooltipped-align-left-1
-  </span>
+  </button>
 </div>
 <div class="d-flex flex-justify-center">
-  <span class="tooltipped tooltipped-nw tooltipped-align-right-2 m-2 p-2 border" aria-label="Tooltipped NW and aligned right.">
+  <button type="button" class="tooltipped tooltipped-nw tooltipped-align-right-2 m-2 p-2 border" aria-label="Tooltipped NW and aligned right.">
     .tooltipped-nw .tooltipped-align-right-2
-  </span>
-  <span class="tooltipped tooltipped-ne tooltipped-align-left-2 m-2 p-2 border" aria-label="Tooltipped NE and aligned left.">
+  </button>
+  <button type="button" class="tooltipped tooltipped-ne tooltipped-align-left-2 m-2 p-2 border" aria-label="Tooltipped NE and aligned left.">
     .tooltipped-ne .tooltipped-align-left-2
-  </span>
+  </button>
 </div>
 <div class="d-flex flex-justify-center">
-  <span class="tooltipped tooltipped-sw tooltipped-align-right-1 m-2 p-2 border" aria-label="Tooltipped SE and aligned right.">
+  <button type="button" class="tooltipped tooltipped-sw tooltipped-align-right-1 m-2 p-2 border" aria-label="Tooltipped SE and aligned right.">
     .tooltipped-sw .tooltipped-align-right-1
-  </span>
-  <span class="tooltipped tooltipped-se tooltipped-align-left-1 m-2 p-2 border" aria-label="Tooltipped SW and aligned left.">
+  </button>
+  <button type="button" class="tooltipped tooltipped-se tooltipped-align-left-1 m-2 p-2 border" aria-label="Tooltipped SW and aligned left.">
     .tooltipped-se .tooltipped-align-left-1
-  </span>
+  </button>
 </div>
 <div class="d-flex flex-justify-center pb-4">
-  <span class="tooltipped tooltipped-sw tooltipped-align-right-2 m-2 p-2 border" aria-label="Tooltipped SE and aligned right.">
+  <button type="button" class="tooltipped tooltipped-sw tooltipped-align-right-2 m-2 p-2 border" aria-label="Tooltipped SE and aligned right.">
     .tooltipped-sw .tooltipped-align-right-2
-  </span>
-  <span class="tooltipped tooltipped-se tooltipped-align-left-2 m-2 p-2 border" aria-label="Tooltipped SW and aligned left.">
+  </button>
+  <button type="button" class="tooltipped tooltipped-se tooltipped-align-left-2 m-2 p-2 border" aria-label="Tooltipped SW and aligned left.">
     .tooltipped-se .tooltipped-align-left-2
-  </span>
+  </button>
 </div>
 ```
 
@@ -101,9 +104,9 @@ Use `.tooltipped-multiline` when you have long content. This style has some limi
 
 ```html live
 <div class="d-flex flex-justify-center pt-6">
-  <span class="tooltipped tooltipped-n tooltipped-multiline m-2 p-2 border" aria-label="This is the tooltip with multiple lines. This is the tooltip with multiple lines.">
+  <button type="button" class="tooltipped tooltipped-n tooltipped-multiline m-2 p-2 border" aria-label="This is the tooltip with multiple lines. This is the tooltip with multiple lines.">
     .tooltipped-multiline
-  </span>
+  </button>
 </div>
 ```
 
@@ -113,8 +116,8 @@ By default the tooltips have a slight delay before appearing. This is to keep mu
 
 ```html live
 <div class="d-flex flex-justify-center pt-4">
-  <span class="tooltipped tooltipped-n tooltipped-no-delay m-2 p-2 border" aria-label="This is the tooltip on the no delay side.">
+  <button type="button" class="tooltipped tooltipped-n tooltipped-no-delay m-2 p-2 border" aria-label="This is the tooltip on the no delay side.">
     .tooltipped-no-delay
-  </span>
+  </button>
 </div>
 ```