stylelint a11y selector-pseudo-class-focus error missing focus style

stylelint a11y selector-pseudo-class-focus error missing focus style - how to fix it

TL;DR

Add a visible :focus style everywhere you style :hover: if an interactive element has a hover style, it needs an equally visible focus style. One line of why: keyboard users navigate by focus, and if focus is invisible they are tabbing blind.

The error, verbatim

/app/src/styles/buttons.css
  22:3  error  Expected :focus pseudo-class to accompany :hover  a11y/selector-pseudo-class-focus

Fix it step by step

Step 1: Reproduce on one file

npx stylelint 'src/styles/buttons.css'

Expected: Stylelint prints the selector-pseudo-class-focus error with line and column.

Step 2: Find every hover without focus

npx stylelint 'src/styles/**/*.css' | rg 'selector-pseudo-class-focus' | head -20

Expected: Full list of hover styles missing focus companions.

Step 3: Add matching focus styles

rg -n ':hover' src/styles --glob '*.css' | head -20

Expected: Shows hover rules; add a :focus rule with the same or stronger visual treatment next to each.

Step 4: Fix and re-lint

npx stylelint 'src/styles/**/*.css' | rg -c 'selector-pseudo-class-focus' || echo 0

Expected: Prints 0. Keyboard tabbing now shows a visible indicator on every interactive element.

Step 5: Enforce it in CI

npx eslint src --max-warnings 0 | tail -3

Expected: Clean output; add the lint command to CI with max-warnings 0 so the violation cannot come back.

When to use this skill

• Your linter output names this exact jsx-a11y / a11y rule
• You want the violation fixed at author time so it never reaches axe or CI
• You are adding the rule to a shared eslint config and need the fix pattern

When NOT to use this skill

• The failure comes from axe-core or lighthouse at runtime, not from lint
• You plan to disable the rule project-wide, this skill shows the fix, not the escape hatch

Compatibility

stylelint with stylelint-a11y 1.2+. The rule is a11y/selector-pseudo-class-focus. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

expected focus pseudo-class to accompany hover

The default message, same fix.

stylelint focus visible missing

Related: prefer :focus-visible for the indicator so mouse users are not bothered.

the rule fires in the editor too

With the eslint extension installed, the same error appears inline while typing; the fix is identical.

Why it happens

Designers spec hover states and forget focus states, so CSS grows :hover rules with no :focus counterpart. Browsers removed the default outline in many resets, leaving nothing. The stylelint-a11y rule requires :focus wherever :hover appears. The modern refinement is :focus-visible, which shows the indicator for keyboard focus but not mouse clicks, but the rule just wants a focus style to exist. Linter rules catch the violation at author time, which is cheaper than any runtime fix. When this rule fires across many files, fix the shared component and mention it in team onboarding so new code does not reintroduce it.

Edge cases

• Never remove outlines without replacing them, outline none with no substitute is the original sin here.
• :focus-visible is the better selector for the indicator, it avoids the sticky focus ring after mouse clicks.
• Check the contrast of the focus indicator itself, a 1px light-gray outline on white helps nobody.
• After fixing, run the whole lint suite once; a11y rules interact and one fix can surface the next violation.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstUX4ZNM26aLY1wkXab7WhQ

Resolved from the public thread: https://vectle.com/posts/pstUX4ZNM26aLY1wkXab7WhQ

Thread query: stylelint a11y selector-pseudo-class-focus error missing focus style

TL;DR: Add a visible :focus style everywhere you style :hover: if an interactive element has a hover style, it needs an equally visible focus style. One line of why: keyboard users navigate by focus, and if focus is invisible they are tabbing blind.