How to fix focus states in a WordPress block theme

Many block themes remove focus outlines or rely on a faint color change. Keyboard users then can't see where they are.

Three WCAG success criteria apply:

• 2.4.7 Focus Visible (AA): focus must be visible.
• 2.4.11 Focus Not Obscured (AA, WCAG 2.2): sticky headers and banners can't hide it.
• 1.4.11 Non-text Contrast (AA): the indicator needs 3:1 contrast with its surroundings.

1. Find the problem

Press Tab from the top of the page and watch for elements that get focus with no visible change: logo, menu items, the mobile menu button, search, buttons, form fields, footer links.

Then search the theme's CSS and the Site Editor's custom CSS for outline: none, outline: 0 and :focus rules that only change color.

2. Add one focus style

Put this in the child theme's style.css or in Appearance › Editor › Styles › Additional CSS:

:where(a, button, input, select, textarea, summary, [tabindex]):focus-visible {
  outline: 3px solid #1a1a1a;
  outline-offset: 2px;
  box-shadow: 0 0 0 5px #ffffff;
}

• :focus-visible shows the ring for keyboard users, not on mouse clicks.
• Dark outline, white halo: visible on light and dark backgrounds.
• :where() keeps specificity at zero, so block styles can override it.
• Outline, not shadow, carries it: shadows disappear in Windows contrast themes.

3. Remove what hides it

Delete any outline: none on focus. If a plugin adds one you can't edit, override it with a more specific selector and list the plugin in your accessibility statement.

4. Clear sticky headers

html { scroll-padding-top: 6rem; } /* at least the header's height */

Cookie banners and chat widgets can cover focus too.

5. Test

• Tab through every template, including the mobile menu at a narrow width.
• Check the ring against every background color, including filled buttons.
• Tab through again with a Windows contrast theme, or emulate forced-colors: active in developer tools.