UI Tooltip: Improve documentation to cover intended accessibility practices#76705
Merged
UI Tooltip: Improve documentation to cover intended accessibility practices#76705
Conversation
mirka
added
[Type] Developer Documentation
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
|
Size Change: 0 B Total Size: 7.66 MB ℹ️ View Unchanged
|
mirka
force-pushed
the
tooltip-documentation
branch
from
fcfc129 to
ab045e2
Compare
ciampo
reviewed
Mar 20, 2026
Contributor
ciampo
left a comment
ciampo
left a comment
There was a problem hiding this comment.
I quite like Base UI docs on Tooltip, they have "Usage guidelines" and "Alternative to tooltips" sections.
I think this may even warrant a dedicated mdx page with a few interactive storybook examples of good practices, bad practices, and alternatives (eg use Popover for infotips)
ciampo
reviewed
Mar 20, 2026
| <> | ||
| <Tooltip.Trigger>Hover me</Tooltip.Trigger> | ||
| <Tooltip.Popup>Tooltip text</Tooltip.Popup> | ||
| <Tooltip.Trigger aria-label="Save">💾</Tooltip.Trigger> |
Contributor
There was a problem hiding this comment.
I also feel that the examlpes could me more useful if they showed a different use case from the one already covered by IconButton?
Member
Author
There was a problem hiding this comment.
Did you have something in mind? I can't really think of a use case that isn't an icon button.
Contributor
There was a problem hiding this comment.
Yeah 😅 Although this is telling on the real utility of Tooltip as a primitive, given that its main usecase is covered by Icon Button and that we don't recommend many other possible use cases
Member
Author
Making a standard infotip pattern/component has been on my todo list, but we currently don't have one yet, and the pattern doesn't exist in Gutenberg 😕 We also haven't aligned on guidance for status messaging. Those two are the most commonly misused patterns. So we actually don't have a lot of "do this instead of this" to officially showcase yet. It's mostly going to be "don't do this" at this point, so I'm thinking we can punt the more comprehensive guidance to later and first make the current docs not be misleading. Is that reasonable, or would you have anything particular to highlight at the moment? |
ciampo
approved these changes
Mar 20, 2026
Contributor
ciampo
left a comment
ciampo
left a comment
There was a problem hiding this comment.
As soon as Popover is added, could we reasonably add similar docs? We would only have a gap for the "Contextual feedback messages" section, but we could leave a "WIP" notive re. adding a toast component.
In the meantime, this PR is already definitely an improvement 🚀
Member
Author
Would love to add an infotip pattern or component for sure 👍 |
adamsilverstein
pushed a commit
that referenced
this pull request
Mar 31, 2026
…ctices (#76705) * Tooltip: Add documentation and update story examples for accessibility * Use @wordpress/icons in WithProvider story example * Fix discoverability of link Co-authored-by: mirka <0mirka00@git.wordpress.org> Co-authored-by: ciampo <mciampini@git.wordpress.org>
adamsilverstein
pushed a commit
that referenced
this pull request
Apr 7, 2026
…ctices (#76705) * Tooltip: Add documentation and update story examples for accessibility * Use @wordpress/icons in WithProvider story example * Fix discoverability of link Co-authored-by: mirka <0mirka00@git.wordpress.org> Co-authored-by: ciampo <mciampini@git.wordpress.org>
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
2 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.
What?
Add a JSDoc description to the
Tooltipcomponent and update the Storybook examples to follow accessibility best practices.Why?
The Tooltip stories previously used text-labeled buttons as triggers, which doesn't reflect the intended use case. Tooltips are meant for controls that lack a visible text label (like icon buttons), and the trigger must be accessibly labeled independently of the tooltip.
We continue to see misuse and misunderstanding of what the
Tooltipcomponents do, and I think the documentation should be blamed first.How?
Tooltip.Rootdocumenting the component's purpose, touch device limitations, accessible labeling requirements, and a cross-reference toIconButton.@wordpress/iconsviaIcon) with explicitaria-labelattributes, demonstrating the recommended accessible pattern.Testing Instructions
See
Tooltipstories in Storybook (@wordpress/ui)AI tools
Actual accessibility guidance authored by me, examples improved on my guidance, executed by Opus 4.6