Agent Wranglers

AXS-13Required

Always show where focus is

Show a clear focus ring on every control when someone reaches it with the keyboard. This is WCAG criterion 2.4.7 (AA).

By Agent Wranglers. Updated .

How to do it

Style :focus-visible with an outline at least 2 CSS px thick, with an offset, and at least 3:1 contrast against the colours around it. The 3:1 contrast is the legal AA bar, from WCAG 1.4.11. The 2 px thickness comes from 2.4.13 (AAA), a best practice beyond the law. Never use outline: none without a replacement. Measure the contrast as Make text easy to read says.

Examples

CSS example

:focus-visible {
  outline: 3px solid var(--focus);
  outline-offset: 2px;
  box-shadow: 0 0 0 5px var(--bg);
}

How to check

A browser test tabs to every control in light and dark mode. For the AA bar, each one's computed outline, border or box-shadow differs from its unfocused state, with at least 3:1 contrast. For the stricter AAA bar, its outline-width is at least 2px.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/accessibility/keyboard-and-focus/focus-indicators">Agent Wranglers accessibility playbook</a>. In code you write, add a comment next to it with the same link.