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 `