diff --git a/index.d.ts b/index.d.ts
index 013475d8a62..ca3b9fca360 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -254,6 +254,7 @@ declare module '@primer/components' {
export interface TooltipProps extends CommonProps {
align?: 'left' | 'right'
+ 'aria-label'?: string
direction?: 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw'
noDelay?: boolean
text?: string
@@ -265,6 +266,7 @@ declare module '@primer/components' {
export interface UnderlineNavProps extends CommonProps {
actions?: React.ReactNode
align?: 'right'
+ 'aria-label'?: string
full?: boolean
label?: string
}
diff --git a/pages/components/docs/Tooltip.md b/pages/components/docs/Tooltip.md
index 8a6306c697d..48bf6051fac 100644
--- a/pages/components/docs/Tooltip.md
+++ b/pages/components/docs/Tooltip.md
@@ -1,12 +1,21 @@
# Tooltip
-The Tooltip component adds a tooltip to add context to elements on the page. The Toolip has a black background by default.
+The Tooltip component adds a tooltip to add context to elements on the page. The Tooltip has a black background by default.
+
+### ⚠️ Usage warning! ⚠️
+Tooltips as a UI pattern should be our last resort for conveying information because it is hidden by default and often with zero or little visual indicator of its existence.
+
+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 Tooltip on elements with no existing text content, or consider using `title` for supplemental information.
+
+
## Default example
```.jsx
- Text with a tooltip
+ Text with a tooltip
```
@@ -21,7 +30,7 @@ Tooltip components get `COMMON` system props. Read our [System Props](/component
| align | String | | Can be either `left` or `right`.|
| direction | String | | Can be one of `n`, `ne`, `e`, `se`, `s`, `sw`, `w`, `nw` | Sets where the tooltip renders in relation to the target. |
| noDelay | Boolean | | When set to `true`, tooltip appears without any delay |
-| text | String | | Text used in `aria-label` (for accessibility).
+| aria-label | String | | Text used in `aria-label` (for accessibility).
| wrap | Boolean | | Use `true` to allow text within tooltip to wrap.
diff --git a/pages/components/docs/UnderlineNav.md b/pages/components/docs/UnderlineNav.md
index aac1c171faf..b23c61004c3 100644
--- a/pages/components/docs/UnderlineNav.md
+++ b/pages/components/docs/UnderlineNav.md
@@ -7,18 +7,20 @@ To use UnderlineNav with [react-router](https://github.com/ReactTraining/react-r
```as={NavLink}``` and omit the ```selected``` prop.
This ensures that the NavLink gets ```activeClassName='selected'```
+**Attention:** Make sure to properly label your `UnderlineNav` with an `aria-label` to provide context about the type of navigation contained in `UnderlineNav`.
+
## Default example
```.jsx
Using {''}
-
-
- Selected
+
+
+ Home
- Bar
- Baz
+ Documentation
+ Support
```
@@ -35,7 +37,7 @@ UnderlineNav and UnderlineNav.Link components get `COMMON` system props. Read ou
| actions | Node | Place another element, such as a button, to the opposite side of the navigation items.|
| align | String | Use `right` to have navigation items aligned right. |
| full | Boolean | Used to make navigation fill the width of the container. |
-| label | String | Used to set the `aria-label` on the top level `