Toolbar: focus state shown on every menu click

[fushar]

After [63009] we seem to be showing the focus state (underline or horizontal line) on every mouse click. I'm not sure but I feel it's distracting. Is this the expected behavior @afercia @joedolson? Also cc @wildworks. See the attached video below.

[wildworks]

Thanks for the report. The border that is added on mouse click feels a bit strange to me.

[ravichudasama01]

I was able to reproduce the reported issue. The focus indicator is displayed after mouse clicks as described in the ticket.

Refer below screenshot:-
​https://prnt.sc/WnTw-ZlxIBJ3

A visual indicator now appears when elements in the admin bar are focused, thanks to [63009]. However, this results in a similar bar appearing when clicking with the mouse, which feels slightly unnatural.

I came up with two approaches:

• Use focus-visible to display the indicator only when an element is focused via keyboard.
• Display the indicator not only on focus but also on hover.

I chose the latter approach for consistency with the sidebar.

Trac ticket: https://core.trac.wordpress.org/ticket/65849

## Use of AI Tools

Used for: Initial code skeleton and test suggestions; final implementation and tests were reviewed and edited by me.

[joedolson]

The accessibility team agrees that making the adminbar more consistent with the behavior we already see in the admin menu makes the most sense, which is the proposal and PR by @wildworks.

[afercia]

focus state shown on every menu click

For clarification: the focus style appearing while clicking a link is a browser native feature. It's not an issue. It's the default behavior.

The inconsistency with the (left) admin menu is that the new focus style for the admin bar is not paired with the :hover state. As such, it 'appears' when clicking. Instead, in the admin menu it is already visible when hovering and it stays visible while clicking.

I reviewed ​the linked PR and it takes a correct approach by making the behavior consistent with the one for the (left) admin menu,

Requesting dev-feedback as per the double committer sign-off workflow during RC.

[joedolson]

Approving for commit, but technically the double-committer sign off is for backporting, not for the commit to trunk.

[joedolson]

In 63190:

Toolbar: Match hover state to focus state.

Follow up to [63009]. The original commit strengthened the focus state in the admin toolbar, but didn't change the hover state. This created a mismatch in behavior where the admin toolbar behaved differently from the primary admin menu, which has a shared hover and focus state.

Apply the focus state to the hover condition as well, so that the behavior matches the admin sidebar.

Props fushar, wildworks, ravichudasama01, afercia, joedolson.
Fixes #65849.

[joedolson]

Reopening for backport to 7.1.

[wildworks]

Approved for backport to the 7.1 branch.

[wildworks]

In 63201:

Toolbar: Match hover state to focus state.

Follow up to [63009]. The original commit strengthened the focus state in the admin toolbar, but didn't change the hover state. This created a mismatch in behavior where the admin toolbar behaved differently from the primary admin menu, which has a shared hover and focus state.

Apply the focus state to the hover condition as well, so that the behavior matches the admin sidebar.

Reviewed by a-fellow-committer, maybe-multiple.
Merges [63190] to the 7.1 branch.

Props fushar, wildworks, ravichudasama01, afercia, joedolson.
Fixes #65849.

[Joen]

I understand the motivation: all items need a focus style, and the one present in the admin bar was insufficient. However it's unfortunate that no design input was solicited for this one, because the solution we've landed on is only technically accessible.

Legibility of focused items is reduced through the thick border sitting in close proximity to the text itself:

The direction of the border jumps around from horisontal to vertical seemingly at random, which is problematic for people on the spectrum for which consistency is important:

This random border is used also in context of submenu items, making it unclear whether something is actionable or decorative:

Overall, it simply doesn't look like a focus style, and it's unclear to me that it fundamentally helps users rather than simply confuse.

It is for the same reason that every component in the WordPress design system uses a singular focus style: a blue 1.5px outside border. A single style applied everywhere except here (and the left admin-menu but with vertical orientation there).

This is late in the process, and absent a patch to improve the focus style, a consideration would be to add :focus-visible handling, so that the bordered focus style is at least seen in the topmost menus before submenus are navigated into, so that the shifting orientation has at least has some connective tissue for users of assistive tech.

[keoshi]

I'd like to offer a design perspective on this fix, because I think it solves the reported problem in the wrong direction.

The original report was about the indicator appearing on mouse click. That's a focus-styling problem, and browsers already have a purpose-built mechanism for it: :focus-visible. It keeps the strong indicator for keyboard navigation and lets the browser suppress it on pointer clicks. This was even presented as option A in the PR.

Instead, the fix went the other way and extended the focus treatment to :hover. There's no accessibility requirement for hover to match focus. Pointer users already have the cursor plus the existing hover color change. What we get in exchange is a heavy 4px bar flashing across the toolbar on every mouse movement, including the user account menu, and on the front end over every theme. It reads to me as noise rather than an affordance.

I understand the argument for the consistency with the sidebar menu, and consistency is a good instinct. But consistency should propagate the best pattern, not the oldest one. The sidebar's shared hover/focus style is a legacy of not having :focus-visible, and matching it doubles down on that legacy in a far more prominent surface instead of elevating everything to a new and better pattern.

I'd propose: keep the strengthened indicator but scope it to :focus-visible, drop the :hover rules, and take a proper design pass at the toolbar's hover and focus states for 7.2. That fixes the reported bug just as well, without changing what the toolbar looks like for every mouse user.

Happy to help with that follow-up.

[wildworks]

Thanks for the opition.

I chose :hover over :focus-visible for two reasons.

• There are no precedents for using :focus-visible in the WordPress core yet.
• I thought it would be good to maintain consistency with the sidebar, where an indicator appears on hover.

However, I am not opposed to changing the styles to use focus-visible.

For your reference, this ticket was also discussed at the Accessibility Bug Scrub.
​https://wordpress.slack.com/archives/C02RP4X03/p1786465729202659

[Joen]

Focus-visible is used for Tabs: ​https://wordpress.github.io/gutenberg/?path=/story/components-tabs--default.

[wildworks]

I am aware that :focus-visible is used in Gutenberg. I am referring to the core only.

[Joen]

Understood, apologies if that came off as terse, but to clarify I think of both as semantically the same, one WordPress, even if they are separate "components" in classic WordPress parlance.

[cbusquets1989]

Thanks for reopening this, @wildworks.

I'd like to come at it from a design angle, since I think we've mostly been talking about implementation so far.

We have three states, and right now two of them look the same:

• Hover — "your pointer is over something interactive." Temporary, follows the mouse.
• Focus — "this is where you are, and what your next keystroke will act on." A position marker.
• Current — "this is the page you're on."

Giving hover and focus the same treatment collapses two of these signals into one. For a keyboard user the indicator stops meaning "you are here" and starts meaning "something is here", because the same visual indicator shows up wherever the mouse happens to be resting. In my opinion, that's not a consistency win.

Two other things:

• It doesn't read as focus to me. Everywhere else in our system focus is an outline around the item. Here it's a heavy bar inside it, in the same colour as the label. And a bar on the left edge of a submenu item reads as "selected", that's what the sidebar uses it for. So in submenus we're now using a selected-state affordance to mean hover.
• It changes shape as you move. Bottom edge at the top level, left edge in submenus. I'd expect a focus indicator to be one thing you learn once. If it changes as you go deeper, it's harder to rely on.

I thought it would be good to maintain consistency with the sidebar, where an indicator appears on hover.

I understand that, and appreciate that we're improving consistency. But the toolbar isn't only an admin surface: it sits on top of every site on the frontend. I don't think the loudest thing on screen should be the bar under the item you're sweeping past on your way somewhere else.

So I'd land where Keoshi did: keep the stronger indicator for focus, leave hover as the colour change it already was. And treat the shape of the focus indicator itself as a design pass for 7.2, which is Joen's point in comment:12.

To address the awkwardness of the indicator appearing only while a Toolbar item is being clicked, [63201] made the indicator show on hover as well as on focus. However, that is a significant change from a design perspective and is open to debate, as noted in the ticket.

The problem to solve was the focus style, not the hover style. So for now, this PR reverts the hover styles and uses :focus-visible instead, so the indicator is shown only on keyboard focus. The transparent outline for Windows High Contrast mode stays on :focus.

The shape of the focus indicator itself is left to a separate design pass.

## Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5
Used for: Applying the selector change and drafting this pull request description. The approach was decided by me, and the result was reviewed and edited by me.

[afercia]

Thanks all for your feedback. A few considerations:

However it's unfortunate that no design input was solicited for this one,

I understand your frustration. I know very well how that feels, having experimented several times a total lack of solicitation of accessibility feedback for many design changes in the last 12 years.

No design feedback was asked because this change to the admin bar uses an existing design pattern. That is, the focus style for the admin menu, which was discussed at length in #28599 and at that time it received plenty of design feedback. I'm not sure I understand why design feedback should be asked again to apply a pattern that is already well established in Core.

Legibility of focused items is reduced through the thick border sitting in close proximity to the text itself

I do recognize this is a potential problem. A proposal was discussed to change the height of the admin bar and make it always 48 pixels for both desktop and mobile. It's 2026 and a tiny horizontal bar with a 32 pixels height is just too small. Increasing the admin bar height should address the concern above. It was just too much for 7.1.

The direction of the border jumps around from horisontal to vertical seemingly at random, which is problematic for people on the spectrum for which consistency is important:

I don't see how else it should have been implemented, given that the admin bar uses both horizontal top-level items and sub-menu items laid-out vertically. Personally, I don't think this is a problem because it uses a pattern that users are already accustomed to: items laid out vertically get the shape on the left, like in the admin menu.

This random border is used also in context of submenu items, making it unclear whether something is actionable or decorative:

Honestly, calling it 'random' is a little too much and sounds like a biased personal opinion. I don't see it random. It's predictable and uses a pattern that is already well established.

Overall, it simply doesn't look like a focus style

Again, this sounds like a personal opinion. Can you please share what is the data, research, and user testing you are basing upon the statement that 'it simply doesn't look like a focus style'?

and it's unclear to me that it fundamentally helps users rather than simply confuse

Again, honestly, this sounds like personal opinion with no data that backs it up.

It is for the same reason that every component in the WordPress design system uses a singular focus style: a blue 1.5px outside border.

As a long time contributor to WordPress you should know that a thin outline as focus style for the admin menu was discussed in #28599 and rejected by the design feedback. As a long-time WordPress contributor I am well aware of the importance of consistent design but this becomes difficult to achieve when the same design feedback becomes contradictory depending on the individual designers involved in the discussion.

:focus-visible

We don't want to use :focus-visible. It only apparently solves the problem. Actually, it assumes that users are either mouse (pointing device) users or keyboard users. It delegates detection to browsers internal heuristics. In the real world, there's not such a thing like only-mouse or only-keyboard users. Actually, all users use a mix of the two, even blind screen reader users. Also, I'd argue that mouse users need a focus style too, to confirm they are targeting the controls correctly. As a low vision user, I benefit a lot from a focus style even when I'm using the mouse or trackpad. So, in general, :focus-visible is not a great solution.

Lastly, the general design considerations should have been discussed on the main ticket #65445. Instead, this ticket is only about the :hover state and should not have been reopened.

Please move any general design consideration to #65445 and reopen it if you like. This ticket should only be about the hover / focus style pairing.

@t-hamano thanks for the PR.
I don't think there is agreement on the ticket about this change. see https://core.trac.wordpress.org/ticket/65445
Also, personally I don't recommend to use :focus-visible and I'm pretty sure others in the accessibility team would agree. Note that, besides hte concerns expressed on the ticket, :focus-visible would introduce one more inconsistnecy with the admin menu.

[wildworks]

If the approach using focus-visible is not acceptable, my opinion for 7.1 is to revert all of [63009][63190]. This means returning to the same state as 7.0. Then, we will resume either or both of #65445 and #65765, and the accessibility and design teams will collaborate again to explore the optimal approach. I understand the importance of accessibility and appreciate your current efforts. However, I cannot ignore the concerns raised by at least three contributors.

In any case, the final decision will need to be made among the release leads and tech leads. cc @joedolson @annezazu

[fushar]

I personally believe, this hover behavior landed too late in the cycle. I think this potentially breaks many plugins. For example, Yoast now has this broken-looking button when hovered:

[keoshi]

@afercia Point taken and I think we can agree there's multiple layers here. Hover, focus, and focus-visible serve different purposes and should stay separate.

The larger point was about stopping overloading hover and overstyling focus. Right now, those have too many problems to be acceptable and I'd argue the styling actually reduces legibility of some items, not to mention other unintended consequences (see @fushar example above).

What do you think about keeping a visible but minimal :focus style so mouse/trackpad/touch users get confirmation too, and layer the a indicator on top via :focus-visible for keyboard/programmatic focus, if needed? That solves the original bug (bar items firing on every click) and your low-vision point at the same time, without extending focus treatment to hover where it doesn't belong.

[joedolson]

In many ways, the focus/hover state I'd actually prefer would be to match the admin sidebar, with the inverted colors. That will have more extensive challenges for extenders, however, so it is a change that would have to land earlier.

The alternative - and potentially more unifying change - would be to eliminate unique focus/hover styling in both the adminbar and the admin sidebar in favor of using the global focus/hover styles used by other elements.

Either of those cases would be better done in 7.2, as they are significant changes. If there's interest in pursuing either of those paths, I think that it would be better for users to delay making any change in 7.1, rather than have a change in design for these elements in three consecutive releases (they already changed in 7.0, and having them change again in both 7.1 and 7.2 is a lot.)

[afercia]

I'm not sure I understand why this styling is a problem in the admin bar when it's basically what WordPress uses in the admin menu since years.

Yoast now has this broken-looking button when hovered:

I think I know, in some way, that they are adding items to the admin bar in non-standard ways :)

That said, personally I already gave my feedback. I'll leave the decision to the release tech leads, of course.

[afercia]

Just one more quick consideration: for the ones who claim that the focus style should be consistent across WordPress, well actually it is largely inconsistent. The work done in Gutenberg for the focus style didn't take into account how it actually works in Core. I created #65878 to keep track of it and illustrate the inconsistencies.

[keoshi]

I'm not sure I understand why this styling is a problem in the admin bar when it's basically what WordPress uses in the admin menu since years.

Just because it works okay in one context, doesn't mean it should applied globally. A style or pattern being available seems like a very low bar to clear.

And I'd argue it's not a good style to begin with, but that's also my personal opinion. :)

[annezazu]

Reading over this thread and trying to get caught up on where we are, I want to echo comments about this landing late in the cycle and that additional changes can be done for 7.2. I agree with @wildworks and what he said below:

If the approach using focus-visible is not acceptable, my opinion for 7.1 is to revert all of [63009][63190]. This means returning to the same state as 7.0.

Please do this. Visually, this does feel like the wrong approach and I'd like more time to figure this out.

[afercia]

I want to echo comments about this landing late in the cycle

Just to be accurate:

The PR related to the focus style has been available for testing since June 15, including a video recording to illustrate the change:
​https://github.com/WordPress/wordpress-develop/pull/12179
Then [63009] was committed on August 4, that is 10 days ago in Beta 4.
I wouldn't call that 'late in the cycle'.
Everyone had a month two months to test it or at least see the video.

The :hover style change was committed in [63190] 3 days ago and yes I'd agree that's late.

That said, I defer to the release lead.

[joedolson]

I do want to push back on any impression that this landed "late in the cycle"; trunk only opened for 7.1 on May 20th, and it was committed on June 15th - that meets any reasonable definition of an early commit for the cycle. The minor change to also render it on :hover did land late, but otherwise this sat in core largely without concern for two months.

I do agree that since the appearance is hotly contested, it may be best to revert the change for this release. But I do want to emphasize that there are *many* problems with the admin bar, and this is quite a small one, compared to the significant overflow problems. I would hope that any treatment of this came with a larger attention to the many other problems with the toolbar.

[annezazu]

I hear you all! Let me be super specific since I do want clearly documented decisions for this release cycle to make it easier for us to follow up on in the future. My concern is the :hover rendering and the resulting visual changes in [63190], backported in [63201]. That landed on August 11 and I don't want it to ship in 7.1.

Follow-up work on the focus indicator itself belongs in 7.2 at this point — #65445 and #65878 look like the right homes for that discussion but let me know if that's wrong. I agree there are broader inconsistencies here and we should get this right, along with improving the rest of the admin bar. I just don't think we can for 7.1 as much as it pains me (and it does).

Then [63009] was committed on August 4, that is 10 days ago in Beta 4.

You're right! I missed this originally and the change 3 days ago made it far more noticeable.

I appreciate everyone discussing this and reacting quickly. These decisions and moments are hard, especially so close to release day. I appreciate the patience in my trying to get up to speed on the hard work here. I know I am still missing details that matter but I'm trying to make the best call I can considering. The good news is this is an area that will continue to be worked on leading into 7.2 so let's embrace continually iteration for our collective users.

[joedolson]

That sounds reasonable to me. I believe that what you're proposing is to revert 63190/63201, so that the focus indicator doesn't impinge on hover behavior. We can then continue to iterate in 7.2

If you confirm that, would be much appreciated!

[wildworks]

That sounds reasonable to me. I believe that what you're proposing is to revert 63190/63201, so that the focus indicator doesn't impinge on hover behavior. We can then continue to iterate in 7.2

Reverting only [63190]/[63201] does indeed remove the indicator on mouse hover, but the indicator displayed on mouse click, which was the original issue raised in this ticket, remains.

If the approach using focus-visible is not acceptable, my opinion for 7.1 is to revert all of [63009][63190]. This means returning to the same state as 7.0.

Please do this. Visually, this does feel like the wrong approach and I'd like more time to figure this out.

My understanding is that this is what we will be doing.

As a result of the discussion, it was decided to revert some or all of the previous commits, so I'm closing this.

Reverts the two changesets that introduced the new Toolbar focus/hover indicator:

• [r63190] — Toolbar: Improve the focus style indication.
• [r63009] — Toolbar: Match hover state to focus state.

With both reverted, no indicator is rendered for the Toolbar focus, hover, or mouse-click states, restoring the visual appearance to what shipped in WordPress 7.0.

Each revert is a separate commit so they can be applied or reviewed independently.

## Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus
Used for: Drafting this pull request description. The code changes are plain git revert of the two changesets above and were reviewed by me.

Note that [r63188] should be reverted as well. It was a tiny follow-up to [r63009].

[annezazu]

Thanks for the patience in my delay in confirming. What Aki did is what I was hoping to see! Thank you for handling.

Note that [r63188] should be reverted as well. It was a tiny follow-up to [r63009].

Nice catch; I have reverted bf0784f3e47f37654ab6f866bb54c1f7e4409b07 as well.

[joedolson]

Marking for commit.

[joedolson]

In 63306:

Toolbar: Revert focus and hover style changes.

Reverts the focus and hover style changes in the admin toolbar. Reverts [63190], [63009], and [63188], restoring the appearance in WordPress 7.0.

Props fushar, wildworks, ravichudasama01, afercia, joen, keoshi, cbusquets1989, annezazu.
Fixes #65849. See #65445.

[joedolson]

Re-opening for backport to the 7.1 branch.

[wildworks]

Reviewed [63306], approved for backport to the 7.1 branch.

[wildworks]

In 63318:

Toolbar: Revert focus and hover style changes.

Reverts the focus and hover style changes in the admin toolbar. Reverts [63190], [63009], and [63188], restoring the appearance in WordPress 7.0.

Reviewed by wildworks.
Merges [63306] to the 7.1 branch.

Props fushar, wildworks, ravichudasama01, afercia, joen, keoshi, cbusquets1989, annezazu.
Fixes #65849. See #65445.