From afe6b700179dabf85cf9cdab14ce7f7d3ed4b69e Mon Sep 17 00:00:00 2001 From: langermank <18661030+langermank@users.noreply.github.com> Date: Wed, 23 Aug 2023 17:52:44 -0700 Subject: [PATCH 01/16] update images --- content/components/tooltip.mdx | 37 +++++++++++++++---- .../accessibility/tooltip-alternatives.mdx | 18 ++++----- 2 files changed, 39 insertions(+), 16 deletions(-) diff --git a/content/components/tooltip.mdx b/content/components/tooltip.mdx index 75d8e4446..407abf85d 100644 --- a/content/components/tooltip.mdx +++ b/content/components/tooltip.mdx @@ -3,8 +3,8 @@ title: Tooltip description: Tooltips add additional context to other UI elements and appear on mouse hover or keyboard focus. reactId: tooltip railsIds: -- Primer::Alpha::Tooltip -- Primer::Tooltip + - Primer::Alpha::Tooltip + - Primer::Tooltip cssId: tooltip --- @@ -13,7 +13,6 @@ import {Link, Text} from '@primer/react' import {Link as GatsbyLink} from 'gatsby' export default ComponentLayout - ## Usage The tooltip component adds a tooltip to add context to interactive elements on the page. @@ -21,15 +20,40 @@ The tooltip component adds a tooltip to add context to interactive elements on t three examples of tooltips on interactive elements + + + + Do use tooltips for icon buttons that serve unique purposes + + + + + Don’t use tooltips for icon buttons that appear in a group of other controls which share the same functionality, + such as opening a context menu. + + + + ## Accessibility ⚠️ 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. + + 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? See Tooltip alternatives for more accessible alternatives. @@ -40,5 +64,4 @@ A tooltip may only be used on an element that is interactive such as a button or ### Tooltip alternatives -Most UI cases don't call for tooltips. Learn some [alternative methods to use in place of tooltips](/../guides/accessibility/tooltip-alternatives). - +Most UI cases don't call for tooltips. Learn some [alternative methods to use in place of tooltips](../guides/accessibility/tooltip-alternatives.mdx). diff --git a/content/guides/accessibility/tooltip-alternatives.mdx b/content/guides/accessibility/tooltip-alternatives.mdx index df31dcf2a..260d24c70 100644 --- a/content/guides/accessibility/tooltip-alternatives.mdx +++ b/content/guides/accessibility/tooltip-alternatives.mdx @@ -30,7 +30,7 @@ Always consider **not** using a tooltip for an improved user experience. Icon buttons with tooltips for edit, favorite, and sponsor Use a tooltip to give a text label to an icon button @@ -38,7 +38,7 @@ Always consider **not** using a tooltip for an improved user experience. Non-interactive text element activating a long and wordy tooltip on hover Don't use tooltips on non-interactive elements @@ -59,7 +59,7 @@ Always consider **not** using a tooltip for an improved user experience. Mock of an icon button and its tooltip with an annotation pointing to the tooltip with 'label' text @@ -80,7 +80,7 @@ If possible, persist the content so it's always available rather than using a to Information about how many discussions can be pinned added to the confirmation dialog Find an appropriate permanent place to display additional information. @@ -88,7 +88,7 @@ If possible, persist the content so it's always available rather than using a to Information about how many discussions can be pinned within tooltip on non-interactive element Don't use a tooltip to add additional helpful information @@ -103,7 +103,7 @@ If the tooltip duplicates content that is already available on the page, remove Pointer hovering over a link with no tooltip Remove any duplicate tooltip text. @@ -111,7 +111,7 @@ If the tooltip duplicates content that is already available on the page, remove Screenshot of tooltip with GitHub username, @inkblotty, on a static span that says @inkblotty Don't set tooltips that duplicate the trigger element content. @@ -134,7 +134,7 @@ Consider using a modal, which is accessible for mobile users and allows you to s Screenshot of GitHub Actions page using a tooltip on a static element to convey long workflow file information Don't place long content inside a tooltip @@ -157,7 +157,7 @@ Consider using a summary disclosure that is accessible for mobile users and also Screenshot of GitHub pricing page using a tooltip to hide and show long descriptions on each point Don't use tooltips on non-interactive elements From 3c42180d943384e452a2d06a8ad378656106dc25 Mon Sep 17 00:00:00 2001 From: langermank <18661030+langermank@users.noreply.github.com> Date: Wed, 23 Aug 2023 18:13:34 -0700 Subject: [PATCH 02/16] cleanup --- content/components/tooltip.mdx | 44 ++++++++++--------- .../accessibility/tooltip-alternatives.mdx | 2 +- 2 files changed, 25 insertions(+), 21 deletions(-) diff --git a/content/components/tooltip.mdx b/content/components/tooltip.mdx index 407abf85d..dca8bb39a 100644 --- a/content/components/tooltip.mdx +++ b/content/components/tooltip.mdx @@ -24,6 +24,30 @@ The tooltip component adds a tooltip to add context to interactive elements on t alt="three examples of tooltips on interactive elements" /> +## Accessibility + + + ⚠️ 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? See Tooltip alternatives for more accessible alternatives. + +We use aria-label for tooltip contents. However, aria-label replaces the text content of an element in screen readers, so only use Tooltip on elements with no existing text content. + +A tooltip may only be used on an element that is interactive such as a button or a link. Even if an element is focusable, a tooltip may only be used if the element does something when it's clicked. + +### Tooltip alternatives + +Most UI cases don't call for tooltips. Learn some [alternative methods to use in place of tooltips](../guides/accessibility/tooltip-alternatives.mdx). + +## Best practices + +If it has been determined that a tooltip is appropriate, follow these best practices. See [alternative methods to use in place of tooltips](../guides/accessibility/tooltip-alternatives.mdx) for more examples of best practices. + - -## Accessibility - - - ⚠️ 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? See Tooltip alternatives for more accessible alternatives. - -We use aria-label for tooltip contents. However, aria-label replaces the text content of an element in screen readers, so only use Tooltip on elements with no existing text content. - -A tooltip may only be used on an element that is interactive such as a button or a link. Even if an element is focusable, a tooltip may only be used if the element does something when it's clicked. - -### Tooltip alternatives - -Most UI cases don't call for tooltips. Learn some [alternative methods to use in place of tooltips](../guides/accessibility/tooltip-alternatives.mdx). diff --git a/content/guides/accessibility/tooltip-alternatives.mdx b/content/guides/accessibility/tooltip-alternatives.mdx index 260d24c70..a9779ecbc 100644 --- a/content/guides/accessibility/tooltip-alternatives.mdx +++ b/content/guides/accessibility/tooltip-alternatives.mdx @@ -80,7 +80,7 @@ If possible, persist the content so it's always available rather than using a to Information about how many discussions can be pinned added to the confirmation dialog Find an appropriate permanent place to display additional information. From bcc57d4ebdbf5c09ddb95e9e84686a5f3857e290 Mon Sep 17 00:00:00 2001 From: langermank <18661030+langermank@users.noreply.github.com> Date: Thu, 24 Aug 2023 14:33:30 -0700 Subject: [PATCH 03/16] attempt to consolidate --- content/components/tooltip.mdx | 209 ++++++++++++++++-- .../accessibility/tooltip-alternatives.mdx | 105 +-------- 2 files changed, 194 insertions(+), 120 deletions(-) diff --git a/content/components/tooltip.mdx b/content/components/tooltip.mdx index dca8bb39a..3eddea9fd 100644 --- a/content/components/tooltip.mdx +++ b/content/components/tooltip.mdx @@ -13,10 +13,6 @@ import {Link, Text} from '@primer/react' import {Link as GatsbyLink} from 'gatsby' export default ComponentLayout -## Usage - -The tooltip component adds a tooltip to add context to interactive elements on the page. - three examples of tooltips on interactive elements -## Accessibility +## Usage ⚠️ 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. + Tooltips as a UI pattern should be the last resort for conveying information as they are hidden by default and often + with zero or little visual indicator of its existence. See tooltip alternaitves below before using this component. -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? See Tooltip alternatives for more accessible alternatives. - -We use aria-label for tooltip contents. However, aria-label replaces the text content of an element in screen readers, so only use Tooltip on elements with no existing text content. - -A tooltip may only be used on an element that is interactive such as a button or a link. Even if an element is focusable, a tooltip may only be used if the element does something when it's clicked. - -### Tooltip alternatives - -Most UI cases don't call for tooltips. Learn some [alternative methods to use in place of tooltips](../guides/accessibility/tooltip-alternatives.mdx). +The tooltip component adds a tooltip to add context to interactive elements on the page. -## Best practices +- Reserve tooltips for components like icon buttons. +- Keep your tooltip text minimal. +- Only include tooltips on other components as a last resort. +- **Never** include tooltips on non-interactive components (`div`, `span`, `p`). -If it has been determined that a tooltip is appropriate, follow these best practices. See [alternative methods to use in place of tooltips](../guides/accessibility/tooltip-alternatives.mdx) for more examples of best practices. + + + Icon buttons with tooltips for edit, favorite, and sponsor + Use a tooltip to give a text label to an icon button + + + Non-interactive text element activating a long and wordy tooltip on hover + Don't use tooltips on non-interactive elements + + @@ -69,3 +77,168 @@ If it has been determined that a tooltip is appropriate, follow these best pract + +## Options + +### Label + + + icon button with tooltip as a label + + For interactive controls with no visible text label, a tooltip can be used to provide one. This label should be + short and descriptive just as you would for a button with visible text. + + + +### Description + + + icon button with tooltip as a description + + For interactive controls that require additional context, a tooltip can be used to provide it. The `label` is also + required, and the description will be announced to a screen reader in addition to the label. Keep the description + short and descriptive. + + + +### Position + +By default, the Tooltip component will position itself below the interactive control in a centered alignment. The position is dependant on the space available within the viewport, and it will never break outside of it. It may appear to the top, bottom, left, or right of the interactive control. + +tooltips rendered in all possible positions surrounding a control + +## Alternatives to tooltips + +### 1. Persist the content + +If possible, persist the content so it's always available rather than using a tooltip, which hides content by default. This ensures that the content is always discovered and surfaced to users regardless of device. + + + + Information about how many discussions can be pinned added to the confirmation dialog + Find an appropriate permanent place to display additional information. + + + Information about how many discussions can be pinned within tooltip on non-interactive element + Don't use a tooltip to add additional helpful information + + + +### 2. Don't duplicate content + +If the tooltip duplicates content that is already available on the page, remove it. + + + + Pointer hovering over a link with no tooltip + Remove any duplicate tooltip text. + + + Screenshot of tooltip with GitHub username, @inkblotty, on a static span that says @inkblotty + Don't set tooltips that duplicate the trigger element content. + + + +### 3. Use a modal + +Consider using a modal, which is accessible for mobile users and allows you to structure content that may otherwise be crammed into a tooltip. + + + + Screenshot of GitHub Actions page with a modal that conveys workflow file information about a runner + Do use a pattern that is accessible to a larger number of users such as a modal + + + Screenshot of GitHub Actions page using a tooltip on a static element to convey long workflow file information + Don't place long content inside a tooltip + + + +### 4. Use a summary disclosure + +Consider using a summary disclosure that is accessible for mobile users and also offers the ability to show or hide content. + + + + Screenshot of GitHub pricing page that uses a summary disclosure to hide and show additional information on each point + Do use a pattern that is accessible to a larger number of users such as a summary disclosure + + + Screenshot of GitHub pricing page using a tooltip to hide and show long descriptions on each point + Don't use tooltips on non-interactive elements + + + +### Other + +If you are unsure which alternative is more suited to your scenario and need help, consult a designer or the GitHub Accessibility team (if you are GitHub staff) for advice. + +## Additional resources + +- [Your tooltips are bogus](https://heydonworks.com/article/your-tooltips-are-bogus/) +- [erb lint rule: NoAriaLabelMisuseCounter](https://github.com/github/erblint-github/blob/main/docs/rules/accessibility/no-aria-label-misuse-counter.md#no-aria-label-misuse-counter) + +## Accessibility + +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? See Tooltip alternatives for more accessible alternatives. + +We use aria-label for tooltip contents. However, aria-label replaces the text content of an element in screen readers, so only use Tooltip on elements with no existing text content. + +A tooltip may only be used on an element that is interactive such as a button or a link. Even if an element is focusable, a tooltip may only be used if the element does something when it's clicked. diff --git a/content/guides/accessibility/tooltip-alternatives.mdx b/content/guides/accessibility/tooltip-alternatives.mdx index a9779ecbc..fd8e9b1fd 100644 --- a/content/guides/accessibility/tooltip-alternatives.mdx +++ b/content/guides/accessibility/tooltip-alternatives.mdx @@ -1,5 +1,5 @@ --- -title: Tooltip alternatives +title: Tooltips description: Most UI cases don't call for tooltips. Learn some alternative methods to use in place of tooltips. --- @@ -7,7 +7,7 @@ import {Box, Text} from '@primer/react' ## Overview -Tooltips are often used to convey information. However, tooltips are rarely appropriate, and its misuse can result in a myriad of accessibility issues. +Tooltips are often used to convey information. However, tooltips are rarely appropriate, and their misuse can result in a myriad of accessibility issues. Always consider **not** using a tooltip for an improved user experience. ## Why? @@ -71,103 +71,4 @@ If you determine that tooltips are appropriate for your use case, make sure to c ## Alternatives to tooltips -### 1. Persist the content - -If possible, persist the content so it's always available rather than using a tooltip, which hides content by default. This ensures that the content is always discovered and surfaced to users regardless of device. - - - - Information about how many discussions can be pinned added to the confirmation dialog - Find an appropriate permanent place to display additional information. - - - Information about how many discussions can be pinned within tooltip on non-interactive element - Don't use a tooltip to add additional helpful information - - - -### 2. Don't duplicate content - -If the tooltip duplicates content that is already available on the page, remove it. - - - - Pointer hovering over a link with no tooltip - Remove any duplicate tooltip text. - - - Screenshot of tooltip with GitHub username, @inkblotty, on a static span that says @inkblotty - Don't set tooltips that duplicate the trigger element content. - - - -### 3. Use a modal - -Consider using a modal, which is accessible for mobile users and allows you to structure content that may otherwise be crammed into a tooltip. - - - - Screenshot of GitHub Actions page with a modal that conveys workflow file information about a runner - Do use a pattern that is accessible to a larger number of users such as a modal - - - Screenshot of GitHub Actions page using a tooltip on a static element to convey long workflow file information - Don't place long content inside a tooltip - - - -### 4. Use a summary disclosure - -Consider using a summary disclosure that is accessible for mobile users and also offers the ability to show or hide content. - - - - Screenshot of GitHub pricing page that uses a summary disclosure to hide and show additional information on each point - Do use a pattern that is accessible to a larger number of users such as a summary disclosure - - - Screenshot of GitHub pricing page using a tooltip to hide and show long descriptions on each point - Don't use tooltips on non-interactive elements - - - -### Other - -If you are unsure which alternative is more suited to your scenario and need help, consult a designer or the GitHub Accessibility team (if you are GitHub staff) for advice. - -## Additional resources - -- [Your tooltips are bogus](https://heydonworks.com/article/your-tooltips-are-bogus/) -- [erb lint rule: NoAriaLabelMisuseCounter](https://github.com/github/erblint-github/blob/main/docs/rules/accessibility/no-aria-label-misuse-counter.md#no-aria-label-misuse-counter) +See [Tooltip interface guidelines](../../components/tooltip.mdx) for example alternatives to using tooltips. From b9874511d9f07e3edde9bce8c75a0692810157b2 Mon Sep 17 00:00:00 2001 From: langermank <18661030+langermank@users.noreply.github.com> Date: Thu, 24 Aug 2023 14:47:57 -0700 Subject: [PATCH 04/16] cleanup --- content/components/tooltip.mdx | 31 ++++++++++------------- src/@primer/gatsby-theme-doctocat/nav.yml | 2 +- 2 files changed, 15 insertions(+), 18 deletions(-) diff --git a/content/components/tooltip.mdx b/content/components/tooltip.mdx index 3eddea9fd..c9b882c8b 100644 --- a/content/components/tooltip.mdx +++ b/content/components/tooltip.mdx @@ -20,8 +20,6 @@ export default ComponentLayout alt="three examples of tooltips on interactive elements" /> -## Usage - ⚠️ Usage Warning ⚠️ @@ -30,13 +28,14 @@ export default ComponentLayout -The tooltip component adds a tooltip to add context to interactive elements on the page. +## Usage -- Reserve tooltips for components like icon buttons. -- Keep your tooltip text minimal. -- Only include tooltips on other components as a last resort. +- Reserve tooltips for components such as icon buttons. +- Keep the tooltip text minimal. - **Never** include tooltips on non-interactive components (`div`, `span`, `p`). +### Best practices + icon button with tooltip as a label For interactive controls with no visible text label, a tooltip can be used to provide one. This label should be @@ -112,7 +111,7 @@ The tooltip component adds a tooltip to add context to interactive elements on t icon button with tooltip as a description For interactive controls that require additional context, a tooltip can be used to provide it. The `label` is also @@ -128,12 +127,18 @@ By default, the Tooltip component will position itself below the interactive con tooltips rendered in all possible positions surrounding a control ## Alternatives to tooltips +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? See Tooltip alternatives for more accessible alternatives. + +We use aria-label for tooltip contents. However, aria-label replaces the text content of an element in screen readers, so only use Tooltip on elements with no existing text content. + +A tooltip may only be used on an element that is interactive such as a button or a link. Even if an element is focusable, a tooltip may only be used if the element does something when it's clicked. + ### 1. Persist the content If possible, persist the content so it's always available rather than using a tooltip, which hides content by default. This ensures that the content is always discovered and surfaced to users regardless of device. @@ -234,11 +239,3 @@ If you are unsure which alternative is more suited to your scenario and need hel - [Your tooltips are bogus](https://heydonworks.com/article/your-tooltips-are-bogus/) - [erb lint rule: NoAriaLabelMisuseCounter](https://github.com/github/erblint-github/blob/main/docs/rules/accessibility/no-aria-label-misuse-counter.md#no-aria-label-misuse-counter) - -## Accessibility - -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? See Tooltip alternatives for more accessible alternatives. - -We use aria-label for tooltip contents. However, aria-label replaces the text content of an element in screen readers, so only use Tooltip on elements with no existing text content. - -A tooltip may only be used on an element that is interactive such as a button or a link. Even if an element is focusable, a tooltip may only be used if the element does something when it's clicked. diff --git a/src/@primer/gatsby-theme-doctocat/nav.yml b/src/@primer/gatsby-theme-doctocat/nav.yml index e831adc9b..21b6d3c66 100644 --- a/src/@primer/gatsby-theme-doctocat/nav.yml +++ b/src/@primer/gatsby-theme-doctocat/nav.yml @@ -48,7 +48,7 @@ url: /guides/accessibility/semantic-html - title: Text resize and respacing url: /guides/accessibility/text-resize-and-respacing - - title: Tooltip alternatives + - title: Tooltips url: /guides/accessibility/tooltip-alternatives - title: Contribute url: /guides/contribute From bc3a41d759a2f3c86f7a59b438b4e17a5e39753f Mon Sep 17 00:00:00 2001 From: langermank <18661030+langermank@users.noreply.github.com> Date: Thu, 24 Aug 2023 14:57:49 -0700 Subject: [PATCH 05/16] fix box hopefully --- content/components/tooltip.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/content/components/tooltip.mdx b/content/components/tooltip.mdx index c9b882c8b..cf7360f7a 100644 --- a/content/components/tooltip.mdx +++ b/content/components/tooltip.mdx @@ -9,17 +9,10 @@ cssId: tooltip --- import ComponentLayout from '~/src/layouts/component-layout' -import {Link, Text} from '@primer/react' +import {Link, Text, Box} from '@primer/react' import {Link as GatsbyLink} from 'gatsby' export default ComponentLayout -three examples of tooltips on interactive elements - ⚠️ Usage Warning ⚠️ @@ -30,6 +23,13 @@ export default ComponentLayout ## Usage +three examples of tooltips on interactive elements + - Reserve tooltips for components such as icon buttons. - Keep the tooltip text minimal. - **Never** include tooltips on non-interactive components (`div`, `span`, `p`). From f8b8de199f6e79b63ab507c4cda79f6edee2905d Mon Sep 17 00:00:00 2001 From: Katie Langerman <18661030+langermank@users.noreply.github.com> Date: Fri, 15 Sep 2023 11:29:56 -0700 Subject: [PATCH 06/16] Update content/components/tooltip.mdx --- content/components/tooltip.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/components/tooltip.mdx b/content/components/tooltip.mdx index cf7360f7a..5a49c7b76 100644 --- a/content/components/tooltip.mdx +++ b/content/components/tooltip.mdx @@ -116,7 +116,7 @@ export default ComponentLayout For interactive controls that require additional context, a tooltip can be used to provide it. The `label` is also required, and the description will be announced to a screen reader in addition to the label. Keep the description - short and descriptive. + short and concise. From 008c153749c98aeae4e612964a5bbef03f648817 Mon Sep 17 00:00:00 2001 From: Katie Langerman <18661030+langermank@users.noreply.github.com> Date: Fri, 15 Sep 2023 11:30:33 -0700 Subject: [PATCH 07/16] Update content/components/tooltip.mdx Co-authored-by: Kate Higa <16447748+khiga8@users.noreply.github.com> --- content/components/tooltip.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/components/tooltip.mdx b/content/components/tooltip.mdx index 5a49c7b76..84ec51ab3 100644 --- a/content/components/tooltip.mdx +++ b/content/components/tooltip.mdx @@ -27,7 +27,7 @@ export default ComponentLayout width="960" role="presentation" src="https://github.com/primer/primitives/assets/18661030/172aa8f6-2273-4719-bb63-8dd678ffcbc9" - alt="three examples of tooltips on interactive elements" + alt="Three examples of tooltips on interactive elements" /> - Reserve tooltips for components such as icon buttons. From eb4070358fae5c3d73d988eff1d773750025a1c0 Mon Sep 17 00:00:00 2001 From: Katie Langerman <18661030+langermank@users.noreply.github.com> Date: Fri, 15 Sep 2023 11:30:57 -0700 Subject: [PATCH 08/16] Update content/components/tooltip.mdx Co-authored-by: Kate Higa <16447748+khiga8@users.noreply.github.com> --- content/components/tooltip.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/components/tooltip.mdx b/content/components/tooltip.mdx index 84ec51ab3..f5bdc4692 100644 --- a/content/components/tooltip.mdx +++ b/content/components/tooltip.mdx @@ -17,7 +17,7 @@ export default ComponentLayout ⚠️ Usage Warning ⚠️ Tooltips as a UI pattern should be the last resort for conveying information as they are hidden by default and often - with zero or little visual indicator of its existence. See tooltip alternaitves below before using this component. + with zero or little visual indicator of its existence. See [tooltip alternatives](___) before using this component. From dc48f22d5465b6106ebf16da62687335b26866ef Mon Sep 17 00:00:00 2001 From: Katie Langerman <18661030+langermank@users.noreply.github.com> Date: Fri, 15 Sep 2023 11:37:36 -0700 Subject: [PATCH 09/16] Update content/components/tooltip.mdx Co-authored-by: Kate Higa <16447748+khiga8@users.noreply.github.com> --- content/components/tooltip.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/components/tooltip.mdx b/content/components/tooltip.mdx index f5bdc4692..c5b1a177e 100644 --- a/content/components/tooltip.mdx +++ b/content/components/tooltip.mdx @@ -30,7 +30,7 @@ export default ComponentLayout alt="Three examples of tooltips on interactive elements" /> -- Reserve tooltips for components such as icon buttons. +- Reserve tooltips to visually surface the label for icon buttons. - Keep the tooltip text minimal. - **Never** include tooltips on non-interactive components (`div`, `span`, `p`). From 1ca516401cba6fb22283e3e8ef3f0a62f534f242 Mon Sep 17 00:00:00 2001 From: Katie Langerman <18661030+langermank@users.noreply.github.com> Date: Fri, 15 Sep 2023 11:37:50 -0700 Subject: [PATCH 10/16] Update content/components/tooltip.mdx Co-authored-by: Kate Higa <16447748+khiga8@users.noreply.github.com> --- content/components/tooltip.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/components/tooltip.mdx b/content/components/tooltip.mdx index c5b1a177e..7d9957a23 100644 --- a/content/components/tooltip.mdx +++ b/content/components/tooltip.mdx @@ -32,7 +32,7 @@ export default ComponentLayout - Reserve tooltips to visually surface the label for icon buttons. - Keep the tooltip text minimal. -- **Never** include tooltips on non-interactive components (`div`, `span`, `p`). +- **Never** include tooltips on non-interactive components (`div`, `span`, `p`) because it will not be accessible for keyboard or screen reader users. ### Best practices From b1d2590206172038319bbb9ed9e97cf6a86efd6d Mon Sep 17 00:00:00 2001 From: langermank <18661030+langermank@users.noreply.github.com> Date: Fri, 6 Oct 2023 11:17:49 -0700 Subject: [PATCH 11/16] feedback --- content/components/tooltip.mdx | 30 +++++------------------------- 1 file changed, 5 insertions(+), 25 deletions(-) diff --git a/content/components/tooltip.mdx b/content/components/tooltip.mdx index cf7360f7a..7c75e29e1 100644 --- a/content/components/tooltip.mdx +++ b/content/components/tooltip.mdx @@ -55,28 +55,6 @@ export default ComponentLayout - - - - Do use tooltips for icon buttons that serve unique purposes - - - - - Don’t use tooltips for icon buttons that appear in a group of other controls which share the same functionality, - such as opening a context menu. - - - - ## Options ### Label @@ -94,8 +72,9 @@ export default ComponentLayout src="https://github.com/primer/design/assets/18661030/b06d4fc2-d4e6-482d-a9b9-05eb866ce3e1" /> - For interactive controls with no visible text label, a tooltip can be used to provide one. This label should be - short and descriptive just as you would for a button with visible text. + For interactive controls with no visible text label such as an icon button, a tooltip can be used to provide one. + This label should be short and descriptive just as you would for a button with visible text. The `label` serves as + the accessible name for the control utilitizing `aria-labelledby` under the hood. @@ -116,7 +95,8 @@ export default ComponentLayout For interactive controls that require additional context, a tooltip can be used to provide it. The `label` is also required, and the description will be announced to a screen reader in addition to the label. Keep the description - short and descriptive. + short and descriptive. The `description` is intended to supplement the control's label by utilitizing + `aria-describedby` under the hood. From 7f69b4ad7da87afc5f3fa5e2a7f62adf12a69e5e Mon Sep 17 00:00:00 2001 From: Katie Langerman <18661030+langermank@users.noreply.github.com> Date: Fri, 6 Oct 2023 11:18:40 -0700 Subject: [PATCH 12/16] Update content/components/tooltip.mdx Co-authored-by: Kate Higa <16447748+khiga8@users.noreply.github.com> --- content/components/tooltip.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/components/tooltip.mdx b/content/components/tooltip.mdx index 7d9957a23..96645141a 100644 --- a/content/components/tooltip.mdx +++ b/content/components/tooltip.mdx @@ -110,7 +110,7 @@ export default ComponentLayout > icon button with tooltip as a description From fb208e7a8c71a1275c240f997408f0d381098cb2 Mon Sep 17 00:00:00 2001 From: langermank <18661030+langermank@users.noreply.github.com> Date: Fri, 6 Oct 2023 11:44:28 -0700 Subject: [PATCH 13/16] more feedback --- content/components/tooltip.mdx | 30 ++++++++++++++++--- .../primer-css-tooltipped.mdx | 20 ++++++------- 2 files changed, 35 insertions(+), 15 deletions(-) diff --git a/content/components/tooltip.mdx b/content/components/tooltip.mdx index 270c8707b..d9c72d463 100644 --- a/content/components/tooltip.mdx +++ b/content/components/tooltip.mdx @@ -80,6 +80,10 @@ export default ComponentLayout ### Description +The `description` is intended to supplement the control's text label by utilitizing `aria-describedby` under the hood, and will be announced to a screen reader in addition to the label. Keep the description short and descriptive. + +#### Icon button with visually hidden label + - For interactive controls that require additional context, a tooltip can be used to provide it. The `label` is also - required, and the description will be announced to a screen reader in addition to the label. Keep the description - short and descriptive. The `description` is intended to supplement the control's label by utilitizing - `aria-describedby` under the hood. + Icon buttons have a visually hidden label utilizing `aria-label`. To instead display that label in a tooltip, the + `label` option should be used. + + + +#### Button with visible label + + + Button labeled Notifications with tooltip as a description + + For buttons that have a visible label, the `description` option can be used to provide additional context. @@ -219,3 +240,4 @@ If you are unsure which alternative is more suited to your scenario and need hel - [Your tooltips are bogus](https://heydonworks.com/article/your-tooltips-are-bogus/) - [erb lint rule: NoAriaLabelMisuseCounter](https://github.com/github/erblint-github/blob/main/docs/rules/accessibility/no-aria-label-misuse-counter.md#no-aria-label-misuse-counter) +- [Rails tooltip linter](https://github.com/primer/view_components/blob/main/lib/primer/view_components/linters/tooltipped_migration.rb) diff --git a/content/guides/development/rails/migration-guides/primer-css-tooltipped.mdx b/content/guides/development/rails/migration-guides/primer-css-tooltipped.mdx index 042cb2ad7..aaf965ecc 100644 --- a/content/guides/development/rails/migration-guides/primer-css-tooltipped.mdx +++ b/content/guides/development/rails/migration-guides/primer-css-tooltipped.mdx @@ -12,7 +12,7 @@ Depending on your usecase, there are two potential migration paths. Tooltips are not visible by default and can easily go unnoticed, so they should only be used as a last resort, and should never be used to convey critical information. -If `.tooltipped` is being set on a non-interactive element (e.g. ``, `
`, `

`), please consider an alternative. There is no way to make a tooltip fully accessible on a non-interactive element. See [Tooltip alternatives](https://primer.style/design/guides/accessibility/tooltip-alternatives/) or consult a designer. +If `.tooltipped` is being set on a non-interactive element (e.g. ``, `

`, `

`), please consider an alternative. There is no way to make a tooltip fully accessible on a non-interactive element. See [Tooltip alternatives](https://primer.style/design/components/tooltip#alternatives-to-tooltips) or consult a designer. ## Option 2: Migrate to the more accessible PVC tooltip @@ -25,9 +25,7 @@ If your tooltip is appropriately set on an interactive element, you can migrate Flagged code: ```html - - Mona Lisa - + Mona Lisa ``` In this above example, we can get rid of the tooltip because it redundantly repeats the text content, like the following @@ -41,9 +39,7 @@ In this above example, we can get rid of the tooltip because it redundantly repe Flagged code: ```html - + ``` In this above example, the information that is conveyed using the tooltip is critical so we should not be using a tooltip to convey it. Update the design to always persist the text. @@ -53,7 +49,11 @@ In this above example, the information that is conveyed using the tooltip is cri Flagged code: ```html - + Primer ``` @@ -61,9 +61,7 @@ Flagged code: In this above example, the information conveyed in this tooltip isn't necessarily critical but supplements the link. If we decide to permanently persist it,we can update the markup like so: ```html - - Primer - + Primer

``` From 6502600b56db18ef207628f99ff68584c79b6d52 Mon Sep 17 00:00:00 2001 From: langermank <18661030+langermank@users.noreply.github.com> Date: Fri, 6 Oct 2023 11:47:29 -0700 Subject: [PATCH 14/16] cleanup --- content/components/tooltip.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/components/tooltip.mdx b/content/components/tooltip.mdx index d9c72d463..a12aee1d2 100644 --- a/content/components/tooltip.mdx +++ b/content/components/tooltip.mdx @@ -43,7 +43,7 @@ export default ComponentLayout alt="Icon buttons with tooltips for edit, favorite, and sponsor" src="https://github.com/primer/primitives/assets/18661030/e9f86af8-3792-4794-af68-ad0efccd8bc8" /> - Use a tooltip to give a text label to an icon button + Use a tooltip to on an icon button to help convey the purpose of the action Date: Fri, 6 Oct 2023 11:51:01 -0700 Subject: [PATCH 15/16] add figma --- content/components/tooltip.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/components/tooltip.mdx b/content/components/tooltip.mdx index ae668ef18..b962f4315 100644 --- a/content/components/tooltip.mdx +++ b/content/components/tooltip.mdx @@ -1,11 +1,12 @@ --- title: Tooltip -description: Tooltips add additional context to other UI elements and appear on mouse hover or keyboard focus. +description: Tooltips add additional context to interactive UI elements and appear on mouse hover or keyboard focus. reactId: tooltip railsIds: - Primer::Alpha::Tooltip - Primer::Tooltip cssId: tooltip +figmaId: tooltip --- import ComponentLayout from '~/src/layouts/component-layout' @@ -239,13 +240,12 @@ If you are unsure which alternative is more suited to your scenario and need hel ## Additional resources - - [Your tooltips are bogus](https://heydonworks.com/article/your-tooltips-are-bogus/) - [erb lint rule: NoAriaLabelMisuseCounter](https://github.com/github/erblint-github/blob/main/docs/rules/accessibility/no-aria-label-misuse-counter.md#no-aria-label-misuse-counter) - [Rails tooltip linter](https://github.com/primer/view_components/blob/main/lib/primer/view_components/linters/tooltipped_migration.rb) - ### Known accessibility issues - +{' '} + From 27254c02a5fa5445251d62f6404007637f55dd08 Mon Sep 17 00:00:00 2001 From: langermank <18661030+langermank@users.noreply.github.com> Date: Fri, 6 Oct 2023 12:22:49 -0700 Subject: [PATCH 16/16] cleanup --- content/components/tooltip.mdx | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/content/components/tooltip.mdx b/content/components/tooltip.mdx index b962f4315..e56602f59 100644 --- a/content/components/tooltip.mdx +++ b/content/components/tooltip.mdx @@ -19,7 +19,8 @@ import {AccessibilityLink} from '~/src/components/accessibility-link' ⚠️ Usage Warning ⚠️ Tooltips as a UI pattern should be the last resort for conveying information as they are hidden by default and often - with zero or little visual indicator of its existence. See [tooltip alternatives](___) before using this component. + with zero or little visual indicator of its existence. See{' '} + tooltip alternatives before using this component. @@ -45,7 +46,7 @@ import {AccessibilityLink} from '~/src/components/accessibility-link' alt="Icon buttons with tooltips for edit, favorite, and sponsor" src="https://github.com/primer/primitives/assets/18661030/e9f86af8-3792-4794-af68-ad0efccd8bc8" /> - Use a tooltip to on an icon button to help convey the purpose of the action + Use a tooltip on an icon button to help convey the purpose of the action - For interactive controls with no visible text label such as an icon button, a tooltip can be used to provide one. - This label should be short and descriptive just as you would for a button with visible text. The `label` serves as - the accessible name for the control utilitizing `aria-labelledby` under the hood. + Icon buttons have a visually hidden label utilizing `aria-label`. To instead display that label in a tooltip, the + `label` option should be used. The `label` serves as the accessible name for the control utilitizing + `aria-labelledby` under the hood. ### Description -The `description` is intended to supplement the control's text label by utilitizing `aria-describedby` under the hood, and will be announced to a screen reader in addition to the label. Keep the description short and descriptive. +The `description` is intended to supplement the control's text label by utilitizing `aria-describedby` under the hood, and will be announced to a screen reader in addition to the label. Keep the description short and concise. #### Icon button with visually hidden label @@ -99,8 +100,8 @@ The `description` is intended to supplement the control's text label by utilitiz src="https://github.com/primer/design/assets/18661030/2d0cd085-2454-406e-8c99-bc8bd3dd20db" /> - Icon buttons have a visually hidden label utilizing `aria-label`. To instead display that label in a tooltip, the - `label` option should be used. + Icon buttons have a visually hidden label utilizing `aria-label`. To provide context in addition to the visually + hidden label, use the `description` option. @@ -119,7 +120,7 @@ The `description` is intended to supplement the control's text label by utilitiz src="https://github.com/primer/design/assets/18661030/a85cc241-c194-498d-b6ad-8e973fd18aca" /> - For buttons that have a visible label, the `description` option can be used to provide additional context. + For buttons that have a visible label, the `description` option can also be used to provide additional context. @@ -246,6 +247,4 @@ If you are unsure which alternative is more suited to your scenario and need hel ### Known accessibility issues -{' '} -