:focus-visible vs outline: none

outline: none on :focus is one of the most damaging accessibility mistakes in web development. It removes the only visual cue keyboard users have for their current position. The fix: use :focus-visible, which shows focus rings only when the user is navigating with a keyboard — not when they click with a mouse.

The browser's heuristic for :focus-visible (from the spec): matches if any of these are true — the element received focus via keyboard, the element is a text input, the element type usually benefits from a visible focus indicator. The heuristic is reliable across Chrome, Firefox, and Safari.

A simpler, modern approach leverages the fact that browsers style :focus-visible correctly by default — just don't override :focus for mouse clicks:

/* ✅ Modern: customize focus-visible, leave focus alone */
:focus-visible {
  outline: 2px solid currentColor;
  outline-offset: 4px;
  border-radius: 4px;
}

The root cause was a category error: the designer saw a visible focus ring on a mouse-clicked button and assumed it was unnecessary. It was — for mouse users. But :focus matches every focus event regardless of input method. Removing outline from :focus with a global rule removed it from keyboard navigation too. There was no way to distinguish mouse focus from keyboard focus in the original CSS — the selector :focus doesn't know how the element received focus. The :focus-visible pseudo-class exists specifically to provide that distinction, but wasn't used here.

The implementation replaced the global reset with a targeted :focus-visible block and an explicit suppression of the ring on mouse-click focus:

/* Remove :focus ring only for mouse/pointer interactions */
*:focus:not(:focus-visible) {
  outline: none;
}

/* Styled ring for keyboard navigation only */
*:focus-visible {
  outline: 2px solid var(--focus-ring-color, #4E7A68);
  outline-offset: 3px;
  border-radius: 4px;
}

The design system also introduced a --focus-ring-color token so individual components could override the ring color for contrast on dark backgrounds without duplicating the selector logic.

Try clicking a button with the mouse in fixed mode — no ring. Then press Tab — ring appears. That's :focus-visible correctly differentiating mouse from keyboard.

Framework-specific pattern for React component libraries — define the focus ring as a design token and apply it through a base component class:

/* tokens.css — design system layer */
:root {
  --focus-ring-color: #4E7A68;
  --focus-ring-width: 2px;
  --focus-ring-offset: 3px;
}

/* base.css — applied to all interactive elements */
.interactive:focus:not(:focus-visible) {
  outline: none;
}
.interactive:focus-visible {
  outline: var(--focus-ring-width) solid var(--focus-ring-color);
  outline-offset: var(--focus-ring-offset);
  border-radius: 4px;
}

Four implementation notes:

1. Use outline, not box-shadow or border. Outline doesn't affect layout, supports border-radius in modern browsers, and works in Windows High Contrast Mode. box-shadow and border do not render in High Contrast Mode.
2. outline-offset creates breathing room. 2–4px offset prevents the ring from overlapping the element's own border, making it visible on both light and dark backgrounds.
3. Dark backgrounds need a different ring color. A dark green ring on a dark background fails WCAG 1.4.11 (non-text contrast). Use a light ring color or a double ring (white outline + colored outline) via outline + box-shadow for complex backgrounds.
4. High Contrast Mode requires outline. Windows High Contrast Mode overrides colors but preserves outline visibility. box-shadow is invisible in High Contrast Mode. Use outline as the primary focus indicator, not a box-shadow workaround.