Make WordPress Core

Opened 12 months ago

Last modified 3 months ago

#41286 new defect (bug)

Focus style and High Contrast Mode

Reported by: afercia Owned by:
Milestone: Future Release 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 https://github.com/WordPress/gutenberg/issues/1562#issuecomment-313476750

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 (1)

41286.diff (5.4 KB) - added by afercia 4 months ago.

Download all attachments as: .zip

Change History (20)

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

12 months ago

#2 @mor10
12 months 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.

12 months ago

#4 @svinkle
12 months ago

I put this CodePen together to conduct a bit of testing: https://codepen.io/svinkle/pen/dRQxMP

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 12 months ago by svinkle (previous) (diff)

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

11 months ago

#6 @afercia
11 months 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
9 months ago

  • Keywords ui-feedback added

#9 @michaelarestad
7 months 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 (https://msdn.microsoft.com/en-us/library/hh771830(v=vs.85).aspx), 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 months ago

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

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

6 months ago

#13 @afercia
6 months 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: http://hanshillen.github.io/HCMDS/hcmode_detection.html
  • 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
4 months ago

Worth mentioning the solution implemented for Gutenberg by Joen Asmussen, see https://github.com/WordPress/gutenberg/pull/5138 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
4 months ago

A pseudo patch for buttons is drafted in https://github.com/WordPress/gutenberg/pull/5526. Perhaps doesn't need to be applied to the active style, but it's a start.

4 months ago

#16 @afercia
4 months 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
3 months 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
3 months 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 3 months ago by Joen (previous) (diff)

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

3 months ago

Note: See TracTickets for help on using tickets.