WordPress 7.1 expands style-state controls for Button blocks, including hover, focus, focus-visible, and active. A visual style can look polished with a pointer while removing the only reliable keyboard focus indicator or creating low contrast in one responsive state.
Use this for themes, pattern libraries, design systems, landing pages, checkout links, and editor extensions that style WordPress Buttons.
Quick answer
Create primary, secondary, destructive, disabled-looking, icon, and long-label button fixtures on light, dark, image, and colored backgrounds. Test pointer hover, keyboard focus-visible, programmatic focus, active press, touch, high zoom, forced colors, and mobile states. Keep a visible focus indicator independent from hover.
What to check first
- Inventory theme.json state styles and CSS selectors for Button links, groups, and custom variations.
- Create fixtures on every background and include normal, long, icon, and multiline labels.
- Tab through controls and record outline, border, shadow, text, background, and offset values.
- Compare :focus and :focus-visible behavior without assuming every browser input method is identical.
- Nest interaction states inside mobile and tablet values and retest contrast and target size.
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Build state fixtures | Inventory theme.json state styles and CSS selectors for Button links, groups, and custom variations. | Every Button variation has a visible keyboard focus indicator. |
| Test keyboard before pointer polish | Create fixtures on every background and include normal, long, icon, and multiline labels. | Hover, focus, focus-visible, and active states preserve readable labels. |
| Correct narrow state rules | Tab through controls and record outline, border, shadow, text, background, and offset values. | Responsive state nesting does not remove focus or reduce target size. |
| Retest responsive nesting | Compare :focus and :focus-visible behavior without assuming every browser input method is identical. | Editor preview and public frontend match after cache purge. |
Why this usually happens
- Hover colors are often reused for focus without checking keyboard visibility.
- Overflow or border-radius rules can clip outlines outside the button wrapper.
- Nested responsive states can override contrast or spacing only at one viewport.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
// Browser console after focusing a Button link
const el = document.activeElement;
const cs = getComputedStyle(el);
({ tag: el.tagName, text: el.textContent.trim(), outline: cs.outline,
outlineOffset: cs.outlineOffset, color: cs.color, background: cs.backgroundColor });
Test scenarios to run
Run the same controlled fixture across these branches. Write down the expected result before testing so a surprising response is easy to identify.
| Scenario | Fixture | Expected result |
|---|
| Keyboard | Tab and Shift+Tab through every button | A clear focus-visible indicator is never clipped or hidden |
| Pointer | Hover then click each style variation | Hover and active states preserve readable text and intent |
| Touch | Tap controls at 390px and 200 percent zoom | Targets remain operable without overlap |
| Forced colors | Enable a high-contrast or forced-colors mode | Focus and control boundaries remain perceivable |
Safe fix order
Use a sequence that makes each result easy to prove. Stop when new evidence changes the scope or owner of the problem.
- Build state fixtures
- Test keyboard before pointer polish
- Correct narrow state rules
- Retest responsive nesting
- Record accessible design tokens
Decision rule
Hold the style change when keyboard focus is invisible or clipped, text contrast fails in any state, active styling hides the control boundary, or touch targets overlap at supported widths.
Production verification checklist
- Every Button variation has a visible keyboard focus indicator.
- Hover, focus, focus-visible, and active states preserve readable labels.
- Responsive state nesting does not remove focus or reduce target size.
- Editor preview and public frontend match after cache purge.
Field notes
- Capture the focused element and the exact input method used to reach it.
- Measure contrast for text and meaningful component boundaries.
- Include buttons near sticky headers, modals, and overflow-hidden containers.
Questions teams ask during testing
Should focus and focus-visible look identical?
They can, but focus-visible is designed to show an indicator when the browser determines that it is useful, especially for keyboard input.
Can a box shadow be the focus indicator?
Yes if it remains clearly visible, has sufficient contrast, and is not clipped.
Why test active separately?
The pressed state can temporarily change contrast, size, or position and should still communicate a usable control.
Mistakes to avoid
- Do not use hover as the only review state.
- Do not remove outlines without an equivalent visible replacement.
- Do not test only one background color.
- Do not rely on color alone to communicate a destructive or selected state.
What to tell the client or owner
Provide the button variation, background, input method, viewport, state, matched selector, computed colors, outline values, contrast result, screenshot, and expected token.
When HandL WP should help
HandL WP can build the Button fixture, map theme and plugin selectors, correct state-specific styles, and test keyboard, pointer, touch, zoom, responsive, and frontend behavior.
If this is active on a production site, test WordPress button accessibility.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references