Aria label consistency

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
   }

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
 <BorderBox p={3}>
-  <Tooltip text="Hello, Tooltip!">Text with a tooltip</Tooltip>
+  <Tooltip aria-label="Hello, Tooltip!">Text with a tooltip</Tooltip>
 </BorderBox>
 ```
 
@@ -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.
 
 

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
 <ExampleHeading>
   Using <Text fontFamily="mono">{'<UnderlineNav.Link>'}</Text>
 </ExampleHeading>
-<UnderlineNav>
-  <UnderlineNav.Link href="#foo" selected>
-    Selected
+<UnderlineNav aria-label="Main">
+  <UnderlineNav.Link href="#home" selected>
+    Home
   </UnderlineNav.Link>
-  <UnderlineNav.Link href="#bar">Bar</UnderlineNav.Link>
-  <UnderlineNav.Link href="#baz">Baz</UnderlineNav.Link>
+  <UnderlineNav.Link href="#documentation">Documentation</UnderlineNav.Link>
+  <UnderlineNav.Link href="#support">Support</UnderlineNav.Link>
 </UnderlineNav>
 ```
 
@@ -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 `<nav>` element. |
+| aria-label | String | Used to set the `aria-label` on the top level `<nav>` element. |
 
 ### UnderlineNav.Link
 | Prop name | Type | Description |

src/Tooltip.js

@@ -5,7 +5,7 @@ import styled from 'styled-components'
 import {COMMON, get} from './constants'
 import theme from './theme'
 
-function TooltipBase({direction, children, className, text, noDelay, align, wrap}) {
+function TooltipBase({direction, children, className, text, noDelay, align, wrap, ...rest}) {
   const classes = classnames(
     className,
     `tooltipped-${direction}`,
@@ -14,7 +14,7 @@ function TooltipBase({direction, children, className, text, noDelay, align, wrap
     wrap && 'tooltipped-multiline'
   )
   return (
-    <span aria-label={text} className={classes}>
+    <span aria-label={text} {...rest} className={classes}>
       {children}
     </span>
   )

src/UnderlineNav.js

@@ -8,10 +8,10 @@ import theme from './theme'
 const ITEM_CLASS = 'UnderlineNav-item'
 const SELECTED_CLASS = 'selected'
 
-function UnderlineNavBase({actions, className, align, children, full, label}) {
+function UnderlineNavBase({actions, className, align, children, full, label, ...rest}) {
   const classes = classnames(className, 'UnderlineNav', align && `UnderlineNav--${align}`, full && 'UnderlineNav--full')
   return (
-    <nav className={classes} aria-label={label}>
+    <nav className={classes} aria-label={label} {...rest}>
       <div className="UnderlineNav-body">{children}</div>
       {actions && <div className="UnderlineNav-actions">{actions}</div>}
     </nav>