explainer.md

• Rationale
• API Proposal
  • Note: Styling non-native elements which should always match focus-visible
• Example heuristic
• Implementation Prototype

Rationale

The status quo, :focus, is quite problematic:

• Many developers disable the default focus ring in their CSS styles, others attempt to style it in concert with their design. The former often seems to be a result of finding the default focus ring both aesthetically unpleasant and confusing to users when applied after a mouse or touch event and introduces accessibility problems. The latter inevitably creates considerably more of the kind of problem that the former was trying to solve.
• Some native elements in some browsers, notably <button> in Chrome, have a "magic" focus style which does not apply unless focus was received via a keyboard interaction.

To deal with this:

• It seems evident that a visual indication of what has focus is only interesting to a user who is using the keyboard to interact with the page. A user using any kind of pointing device would only be interested in what is in focus if they were just about to use the keyboard - otherwise, it is irrelevant and potentially confusing.
• Thus, if we only show the focus ring when relevant, we can avoid user confusion and avoid creating incentives for developers to disable it.
• A mechanism for exposing focus ring styles only when the keyboard is the user's current input modality gives us this opportunity.

API Proposal

/* override UA stylesheet if necessary */
:focus {
  outline: 0;
}

/* establish desired focus ring appearance for appropriate input modalities */
:focus-visible {
  outline: 2px solid blue;
}

:focus-visible matches native elements that are

1. focussed; and
2. would display a focus ring if only UA styles applied

Additionally, :focus-visible matches non-native elements as if they were native button elements.

Note: Styling non-native elements which should always match focus-visible

This is not currently part of the spec, but a mechanism is needed to explain the ability of native text fields to match :focus-visible regardless of how focus arrived on the element.

Consider an author creating a custom element, custom-texty-element, which they believe should show a focus ring on mouse click. By default, the default :focus-visible user agent style will not show a focus ring when this element receives focus via mouse click. However, if the author were to style the element via :focus, they could not recreate the browser's default outline style reliably:

custom-texty-element:focus {
   outline: ???;
}

Either of the following two new primitives would allow the author to show the default focus ring on click for this element:

1. Add a new keyword value to the outline shorthand that represents whatever the default UA ::focus-visible is. Then authors can do:

    custom-texty-element:focus {
        outline: platform-default-focus-outline-style-foo;
    }
   

2. Add a new CSS property that controls "keyboard modality" vs non-"keyboard modality" behavior, e.g.

    custom-texty-element {
        show-focus-visible-foo: always | keyboard-only;
    }
   

("-foo" placeholder indicates that these names are by no means final!)

While either of these primitives would suffice, having both would provide more flexibility for authors.

Example heuristic

The heuristic used to decide the current modality should not be defined normatively. An example heuristic is to update modality on each style recalc: if the most recent user interaction was via the keyboard; and the key press did not include a meta, alt/option, or control key; then the modality is keyboard. Otherwise, the modality is not keyboard.

See the web platform tests which check against the proposed behavior.

Implementation Prototype

The tiny focus-visible.js provides a prototype intended to achieve the goals we are proposing with technology that exists today in order for developers to be able to try it out, understand it and provide feedback. It sets a .js-focus-visible class on the body element to provide a way to disable focus styles only when the polyfill is loaded. It also sets a .focus-visible class on the active element if the script determines that the keyboard is being used. This attribute is removed on any blur event.

This allows authors to write rules which show a focus style only when it would be relevant to the user. Note that the prototype does not match the proposed API - it is intended to give developers a feel for the model rather than to provide a high-fidelity polyfill.