Repository navigation
Conversation
🤖 PR meta 🤖🎉 PropsIf 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. Updated as activity occurs, without notifying anyone named here. Add the 📦 Bundle sizeSize Change: 0 B Total Size: 8.38 MB
⚡ PerformanceShow the resultsClient side metrics exclude the server response time. front-end-block-theme
front-end-classic-theme
media-processing
media-upload
post-editor
site-editor
🏁 Flaky testsSome tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information. refuses the drop and uploads nothing in
|
|
|
||
| ## Add prefix icons | ||
|
|
||
| > For the best visual results, use prefix icons on every item in a group, or use no prefix icons in that group. If one item needs a prefix icon, prefer adding meaningful icons to all the other items too. Avoid using an icon to highlight just one item in a group. |
There was a problem hiding this comment.
If one item needs a prefix icon, prefer adding meaningful icons to all the other items too.
It could be me, but this reads like encouragement to fill the group with icons, even if they aren't needed for other items. However, it may be more effective to omit the icon for a single item, rather than overwhelming the group with unnecessary icons.
What do you think?
There was a problem hiding this comment.
Agreed. I think a lot of the present critique centres around vertical alignment, where if some menu items in a group have icons and others don't, it creates whitespace and visual rivers. In that sense, perhaps there could be a guideline along the lines of: every icon in a group should either have, or not have icons, with no mixing in the same group.
There was a problem hiding this comment.
Agreed. The guidance now favors omitting a single icon rather than adding unnecessary icons to the group
There was a problem hiding this comment.
Indeed. Let's unpack this.
In the previous menu, we were able to items with and without icons, because icons were on the right side of the menu. The downside was that any menu item that had a suffix, e.g. shortcut, would get very noisy if it also had an icon. Designwise, you either had an icon, or a suffix.
That's solved with the new menu which keeps the suffix on the right, but moves the icon on the left. The tradeoff is that now if we mix icon items with iconless items, you get visual rivers of whitespace from the indentation of iconless icons.
Absent reverting to the old behaviour (which I don't think we should), or a way to make iconless items work non-indented next to items with icons, the net effect is, to be reductive: either all items in a group should have icons, or none of them should. This is the MacOS model, and can look through a variety of MacOS items to see this behavior in effect. The key benefit: things line up across.
Based on the above, we could go this direction:
Prefix icons
Don't mix iconless menu items with icon menu items. Either all items in a group should have prefix icons, or none of them should have.
This is to avoid visual rivers of iconless and icon menu items and create strong scannable vertical alignment lines to benefit legibility.
When should you use an icon menu item? When it is a key menu item that needs an additional visual affordance or prominence. If it sits in a large group of other items, consider whether it sits in the correct group, or needs its own.
Groups don't have to have headings, they can also be implied by separators.
There was a problem hiding this comment.
Updated the guidance to allow useful prominence for a key action and suggest reconsidering its grouping when it is the only item that needs an icon. It still discourages adding unnecessary icons to make a group match.
ciampo
changed the title
|
I'll pause work on this PR while we experiment with a different layout behaviour in #84028, where adding an icon doesn't cause all other items in the group to shift. Once we settle on an approach, I'll resume the work here. |
b710246 to
3d0f118
Compare
|
Updated after the new direction taken with #84028, and ready for a new round of review |
This branch has not been deployed
3 participants
Follow-up to the icon guidance discussion in #83993, updated for the layout changes in #84028.
What?
Clarify when Menu items benefit from icons or descriptions, including useful prominence for key actions. Prefer icons on every item in a group or none, while documenting the supported mixed layout and suggesting regrouping when only one item needs an icon. Favor short labels that stand on their own and reserve descriptions for essential context.
Why?
Consistent icon usage helps users scan a menu, but it should not encourage unnecessary icons. Mixed icon usage no longer leaves an empty icon space.
How?
Keep the usage guide, component descriptions, and prop documentation focused on when icons and descriptions help. Revise stories to use meaningful icons and fewer descriptions, with separate examples for mixed icons and wrapping.
Testing Instructions
Testing Instructions for Keyboard
Open each menu with Enter or Space, navigate with the arrow keys, and close it with Escape. Focus should return to the trigger.
Use of AI Tools
Codex updated the documentation and Storybook examples, ran local verification, and performed an independent adversarial review.