Make WordPress Core

Opened 7 years ago

Closed 5 years ago

Last modified 4 years ago

#41286 closed defect (bug) (fixed)

Focus style and High Contrast Mode

Reported by: afercia's profile afercia Owned by: afercia's profile afercia
Milestone: 5.1 Priority: normal
Severity: normal Version:
Component: Administration Keywords: has-screenshots ui-feedback has-patch
Focuses: ui, accessibility Cc:


Noticed during work done on Gutenberg, thanks to Simply Accessible. See

Operating systems have a high contrast mode to switch to a few-colors/high contrast version of what's rendered on the screen. While this seems to not cause issues on macOS, it does on Windows High Contrast Mode.

People with various vision issues use high contrast mode. People working in dark environments, for example TV production studios, often use it.

Windows High Contrast Mode removes any CSS box-shadow. Most of the WordPress focus styles in the admin are built with multiple box-shadows. As a consequence, with Windows High Contrast Mode turned on, there's no focus indication at all.

In order to be visible in High Contrast Mode, focus styles need to use an outline or a border. There are different techniques that work, they'd need to be tested across different platforms, browsers. etc. Also, WordPress sometimes makes use of the "circular focus" that would need some special treatment.

Worth noting, on Windows the High Contrast Mode works well with just Internet Explorer and Edge. Chrome doesn't support it (it has a dedicated extension and alternative themes). Firefox supports it partially.

It would be great to experiment new and improved focus styles. At the very least, the inner box-shadow could be replaced with an outline, that would probably change very little visually and allow focus to work in High Contrast Mode.

However, there are pending tickets on Trac and ongoing discussions to experiment new focus styes. See for example #34957, #34904, and #28599. This could be a good opportunity to give some new traction to those tickets and improve the focus styles both visually and for accessibility.

Screenshots in Microsoft Edge:

Current (note: the "Published" link is focused):

Native browser outline:

Testing a 1px solid outline:

Attachments (3)

41286.diff (5.4 KB) - added by afercia 6 years ago.
41286.2.diff (5.3 KB) - added by afercia 5 years ago.
41286.3.diff (8.7 KB) - added by afercia 5 years ago.

Download all attachments as: .zip

Change History (35)

This ticket was mentioned in Slack in #accessibility by afercia. View the logs.

7 years ago

#2 @mor10
7 years ago

This is a great opportunity to take another look at focus states in Gutenberg and across WordPress admin. The drop-shadow approach currently in use reads to some users as dated, and counteracts the natural behavior of the browser.

Looking at other services it seems one of three approaches are taken where focus states / high contrast displays are concerned:

  1. Rely on default browser behavior. It looks less pretty than what we have now, but it works as intended everywhere afaik.
  2. Combine :focus and :hover states where appropriate (might not be as relevant to us as there are reasons for having separate focus and hover states).
  3. Adopt a flat-design approach where focus state translates to a solid outline or flat background color change or both.

My vote is for 1 or 3.

This ticket was mentioned in Slack in #accessibility by rianrietveld. View the logs.

7 years ago

#4 @svinkle
7 years ago

I put this CodePen together to conduct a bit of testing:

Attached below are a couple GIF images showing the focus styles in a high contrast (Win7/IE10) and non high contrast environments.

Test results

  1. Using browser default focus states are always encouraged as this is what the user will be most familiar with and will be able to recognize.
  1. Using outline is also a good option as this displays nicely with the default color scheme of the theme. The downside is slightly limited styling available (cannot apply rounded corners.)
  1. Using a border for the focus state also work and has more styling options available. The downside is border adds extra width to the element on :focus, creating a “bump” effect. This is not likely ideal.
  1. It is possible to get around this “bump” effect by applying transparent border to the element by default. The downside here is this default border will always be displayed in a high contrast theme, defeating the purpose really.
  1. Using a background color for a focus state is not really an option as older versions of Windows/IE remove background styles in high contrast themes (Edge browser does not remove these styles.)
  1. Repeating the default styling here to make sure I’ve reached the end of the list.


I’d suggest relying on default focus styles as this would have the most consistent and reliable support. Failing that, using outline would also suffice.

I would also recommend including a :focus selector when a :hover selector is used by default, unless custom :focus styles are required.

GIF demonstration

Non high contrast theme

Animated GIF of a user tabbing through list of links as described above in non high contrast theme.

High contrast theme

Animated GIF of a user tabbing through list of links as described above in Windows high contrast theme.

Last edited 7 years ago by svinkle (previous) (diff)

This ticket was mentioned in Slack in #accessibility by afercia. View the logs.

7 years ago

#6 @afercia
7 years ago

  • Milestone changed from Awaiting Review to Future Release

Moving to Future Release as something that should be definitely be addressed, as per today's bug scrub.

#8 @melchoyce
7 years ago

  • Keywords ui-feedback added

#9 @michaelarestad
7 years ago

This is a tough one. I don't know much about high contrast mode in Windows. I did spot a media query for it (, but it was dropped in Edge (I think). If we could detect it in Windows, we could replace the shadow with outline just when active. Any ideas on detecting high contrast mode?

On a Mac, the box shadows work in my tests. Anyone on Linux able to weigh in as well?

#11 @michaelarestad
7 years ago

@sami.keijonen Oh nifty! And a Safari media query.

This ticket was mentioned in Slack in #accessibility by afercia. View the logs.

7 years ago

#13 @afercia
6 years ago

Discussed during today's weekly a11y bug-scrub, reporting here some thoughts emerged during the discussion, for reference:

  • maybe use '-ms-high-contrast' as CSS hack to target Windows High Contrast Mode? Seems as of Microsoft Edge, -ms-high-contrast: none is no longer supported
  • Hans Hillen wrote a JS library for detecting high contrast mode; we could experiment with that:
  • use system color keywords? They were experimented a bit in Gutenberg with not so great results, as they vary across OSes
  • the only proper way would be using outline/border for focus styles, it feels like that’s the _right_ way, tough change to make, though
  • worth noting some focus style refactoring has been discussed for quite a long time

#14 @afercia
6 years ago

Worth mentioning the solution implemented for Gutenberg by Joen Asmussen, see which uses a 2 pixels transparent outline on focus:

It relies on the fact that Windows High Contrast mode omits box shadows entirely, but it shows any border or outline, even if they are transparent. We leverage that to show thick and visually helpful focus outlines in this high contrast mode — 2px solid transparent. They will show up in high contrast mode, not in normal mode. See also this codepen.

#15 @Joen
6 years ago

A pseudo patch for buttons is drafted in Perhaps doesn't need to be applied to the active style, but it's a start.

6 years ago

#16 @afercia
6 years ago

  • Keywords has-patch added

41286.diff is a first pass to apply the solution by @Joen. In core, not only buttons but also other elements need the transparent outline: normal links, form elements, admin menu items, etc. Still to do:

  • custom focusable controls in core that need a focus style
  • the Customizer (seems it doesn't inherit almost anything from the changes in this patch)

@Joen the patch should be good enough to be tested for buttons and links in the Gutenberg UI.

I'll try to attach a few screenshots soon.

#17 @afercia
6 years ago

A few screenshots:

I'm not sure the WP buttons should use an outline-offset, see below:

Without offset they look better and consistent with other Gutenberg buttons:


IE11 WP button

IE11 link

Note: all links and form controls (inputs, checkbox, radio, textarea, select) use the transparent outline, nearly impossible to screenshot them all :)

#18 @Joen
6 years ago

I won't have time to test the patch in the near future, but based on the screenshots alone, looks good to me 👍 👍

Whether there's an outline-offset or not, I have no strong opinion of, up to you. Though do note that it's virtually zero effort for us to address things in Gutenberg in this phase. So if for example the buttons all look better with an outline-offset in the rest of the admin, not the editor, then we can address the outline offset in Gutenberg to match that of the buttons. Either way, let me know.

Last edited 6 years ago by Joen (previous) (diff)

This ticket was mentioned in Slack in #accessibility by afercia. View the logs.

6 years ago

#20 @afercia
6 years ago

  • Milestone changed from Future Release to 5.0

For parity with what Gutenberg does, it would be great to have it together with the Gutenberg release. Setting the milestone to 5.0.

This ticket was mentioned in Slack in #accessibility by rianrietveld. View the logs.

6 years ago

This ticket was mentioned in Slack in #design by karmatosed. View the logs.

6 years ago

#23 @JoshuaWold
6 years ago

The suggested screenshots ( offer improvement on the high contrast interface and clean things up.

Would be great to have some further review from a design perspective to validate other elements, but from a quick look this looks like a great direction.

#24 @pento
6 years ago

  • Milestone changed from 5.0 to 5.1

#25 @afercia
5 years ago

  • Keywords needs-refresh added
  • Owner set to afercia
  • Status changed from new to assigned

WIll try to refresh the patch for 5.1, as this change complements what the new Block Editor already does.

5 years ago

#26 @afercia
5 years ago

  • Keywords needs-refresh removed

41286.2.diff is a refreshed patch against trunk.

5 years ago

#27 @afercia
5 years ago

41286.3.diff adds Windows High Contrast mode focus style to media and media views.

#28 @afercia
5 years ago

  • Resolution set to fixed
  • Status changed from assigned to closed

In 44544:

Accessibility: Add focus styles for Windows High Contrast mode.

Introduces in core new focus styles dedicated to Windows High Contrast mode. The
new styles use a transparent CSS outline as already explored in the Block Editor.
This first part covers some of the main user interface controls like buttons, links,
and media views elements. Other parts will be addressed in the next future.

Fixes #41286.

#29 @afercia
5 years ago

When clicking on a menu sub-item, there's now a clearly visible outline that "flashes":

This happens because the transparent outline for Windows High Contrast mode gets a CSS transition and its color transitions from the current color to transparent. See the existing CSS for the menu sub-items:

#adminmenu .wp-not-current-submenu li > a,
.folded #adminmenu .wp-has-current-submenu li > a {
	padding-right: 16px;
	padding-left: 14px;
	transition: all .1s ease-in-out;

There's the need to be either more specific and not use all or reset the transition for the outline property.

#30 @afercia
5 years ago

In 44575:

Accessibility: Exclude the Windows High Contrast mode transparent outline from the CSS transition after [44544].

See #41286.

This ticket was mentioned in Slack in #core-media by antpb. View the logs.

5 years ago

#32 @afercia
4 years ago

In 48293:

Accessibility: Improve the focus style for Windows High Contrast mode in various parts of the admin interface.

Continues the introduction in core of new focus styles dedicated to Windows High Contrast mode. The new styles use a transparent CSS outline.
This change covers some parts of the interface for the meta boxes, Widgets, and the Customizer.

Props joedolson, kjellr, antpb, mikeschroder, Hareesh Pillai.
See #41286, #45910.
Fixes #47117.

Note: See TracTickets for help on using tickets.