[docs] Make tooltips describe their visible text triggers#47658
Open
silviuaavram wants to merge 4 commits intomui:masterfrom
Open
[docs] Make tooltips describe their visible text triggers#47658silviuaavram wants to merge 4 commits intomui:masterfrom
silviuaavram wants to merge 4 commits intomui:masterfrom
Conversation
Netlify deploy previewBundle size report
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves the tooltip documentation by restructuring accessibility guidance and updating code examples to follow best practices. The changes move the label vs description explanation to a new "Relationship" section placed earlier in the documentation, and update the Accessibility section to be more concise and focused on general accessibility requirements.
Changes:
- Added new "Relationship: label vs description" section explaining when to use
describeChildprop - Updated Accessibility section to focus on general requirements rather than implementation details
- Added
describeChildprop to tooltip examples where triggers have visible text labels
Reviewed changes
Copilot reviewed 36 out of 36 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tooltips.md | Restructured documentation with new Relationship section and updated Accessibility section; added describeChild to disabled button example |
| VariableWidth.tsx/js | Added describeChild to all tooltip instances wrapping buttons with visible text |
| TriggersTooltips.tsx/js | Added describeChild to all tooltip examples demonstrating trigger behaviors |
| TransitionsTooltips.tsx/js | Added describeChild to tooltips wrapping buttons with visible text |
| TooltipOffset.tsx/js | Added describeChild to tooltip wrapping button with visible text |
| TooltipMargin.tsx/js | Added describeChild to tooltip wrapping button with visible text |
| PositionedTooltips.tsx/js | Added describeChild to tooltips demonstrating positioning (top, left, right, bottom) |
| NonInteractiveTooltips.tsx/js | Added describeChild to tooltip wrapping button with visible text |
| FollowCursorTooltips.tsx/js | Added describeChild to tooltip wrapping Box with visible text |
| DisabledTooltips.tsx/js | Added describeChild to tooltip wrapping disabled button with visible text |
| DelayTooltips.tsx/js | Added describeChild to tooltip wrapping button with visible text |
| CustomizedTooltips.tsx/js | Added describeChild to styled tooltip components wrapping buttons with visible text |
| ControlledTooltips.tsx/js | Added describeChild to controlled tooltip wrapping button with visible text |
| ArrowTooltips.tsx/js | Added describeChild to tooltip wrapping button with visible text |
| AnchorElTooltips.tsx/js | Added describeChild to virtual element tooltip wrapping Box with visible text |
| Preview files | Updated preview snippets to reflect describeChild additions in main files |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ## Relationship: label vs description | ||
|
|
||
| By default, the tooltip only labels its child element. | ||
| This is notably different from `title` which can either label **or** describe its child depending on whether the child already has a label. |
Contributor
There was a problem hiding this comment.
Suggested change
| This is notably different from `title` which can either label **or** describe its child depending on whether the child already has a label. | |
| This is notably different from `title` which can either label or describe its child depending on whether the child already has a label. |
|
|
||
| {{"demo": "BasicTooltip.js"}} | ||
|
|
||
| ## Relationship: label vs description |
Contributor
There was a problem hiding this comment.
Suggested change
| ## Relationship: label vs description | |
| ## Labels and descriptions |
Comment on lines
+27
to
+33
| For example, in: | ||
|
|
||
| ```html | ||
| <button title="some more information">A button</button> | ||
| ``` | ||
|
|
||
| the `title` acts as an accessible description. |
Contributor
There was a problem hiding this comment.
Suggested change
| For example, in: | |
| ```html | |
| <button title="some more information">A button</button> | |
| ``` | |
| the `title` acts as an accessible description. | |
| For example, in the element below, the `title` acts as an accessible description: | |
| ```html | |
| <button title="some more information">A button</button> |
| ``` | ||
|
|
||
| the `title` acts as an accessible description. | ||
| If you want the tooltip to act as an accessible description, you can pass `describeChild`. |
Contributor
There was a problem hiding this comment.
Suggested change
| If you want the tooltip to act as an accessible description, you can pass `describeChild`. | |
| If you want the tooltip to act as an accessible description, you can pass the `describeChild` prop. |
|
|
||
| the `title` acts as an accessible description. | ||
| If you want the tooltip to act as an accessible description, you can pass `describeChild`. | ||
| Note that you shouldn't use `describeChild` if the tooltip provides the only visual label. Otherwise, the child would have no accessible name and the tooltip would violate [success criterion 2.5.3 in WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/label-in-name.html). |
Contributor
There was a problem hiding this comment.
Suggested change
| Note that you shouldn't use `describeChild` if the tooltip provides the only visual label. Otherwise, the child would have no accessible name and the tooltip would violate [success criterion 2.5.3 in WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/label-in-name.html). | |
| You shouldn't use `describeChild` if the tooltip provides the only visual label. | |
| In that case, the child would have no accessible name and the tooltip would violate [success criterion 2.5.3 in WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/label-in-name.html). |
| If you want the tooltip to act as an accessible description, you can pass `describeChild`. | ||
| Note that you shouldn't use `describeChild` if the tooltip provides the only visual label. Otherwise, the child would have no accessible name and the tooltip would violate [success criterion 2.5.3 in WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/label-in-name.html). | ||
|
|
||
| Consequently, if the trigger already has either visible text or an `aria-label`, use the tooltip as a description and pass the `describeChild` prop. Otherwise, use the default behavior and let the tooltip label the trigger. |
Contributor
There was a problem hiding this comment.
Suggested change
| Consequently, if the trigger already has either visible text or an `aria-label`, use the tooltip as a description and pass the `describeChild` prop. Otherwise, use the default behavior and let the tooltip label the trigger. | |
| If the trigger already has either visible text or an `aria-label`, use the tooltip as a description and pass the `describeChild` prop. | |
| Otherwise, you can use the default behavior and let the tooltip label the trigger. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #47246
describeChildpassed to them, because their triggers already have visible text, and the aria-label added by Tooltip is overriding the text for screen readers, which is not what we want.describeChildbut we should replace visible text buttons with icon buttons.