Fix: State styles – clear background-image when hover sets a solid background-color

[i-am-chitti]

What?

Closes #78900

Emits background-image: none !important when a state (e.g. :hover) sets a solid background-color without its own gradient, preventing the default-state gradient from bleeding through.

Why?

When a block instance has a gradient applied to its default state and a solid background color applied to a pseudo-state like :hover, the hover color never appears. The gradient keeps winning despite the state styles using !important.

This is a CSS property mismatch: gradients render as background (shorthand) or background-image, while solid colors render as background-color. Since !important only resolves ties between declarations of the same property, the gradient image layer is never cleared by the hover rule.

How?

Mirrors the existing border-style fallback pattern already in the states support:

• PHP (lib/block-supports/states.php): Added gutenberg_get_state_declarations_with_background_resets(), called alongside the existing gutenberg_get_state_declarations_with_fallback_border_styles(). When compiled declarations include background-color but no background or background-image, it appends background-image: none !important.

• JS (packages/block-editor/src/hooks/style.js): Added getStateBackgroundResetCSS() helper wired into getStateStylesCSS(). Checks color.gradient, background.gradient, and background.backgroundImage to avoid adding the reset when the state itself sets a gradient.

Both the legacy color.gradient path (emits background shorthand) and the modern background.gradient path (emits background-image) are covered.

Testing Instructions

Note: The :hover state panel in the editor requires Gutenberg plugin with the state styles feature active.

1. Open a post or page in the editor.
2. Insert a Buttons block.
3. Select the inner Button block.
4. In the block inspector sidebar, apply a custom background gradient (e.g. blue-to-purple) on the default/normal state.
5. Using the state dropdown in the sidebar, switch to the :hover state.
6. Apply a solid background color (e.g. white #ffffff).
7. Save the post and view it on the frontend.
8. Hover over the button.

Expected: The solid hover color replaces the gradient on hover.
Before this fix: The gradient remained visible on hover despite the solid color being set.

Testing Instructions for Keyboard

The fix is purely server-side/CSS — no interactive UI changes. Standard keyboard navigation of the editor is unaffected.

Screenshots or screencast

Before

Screen.Recording.2026-06-06.at.7.31.23.PM.mp4

After

Screen.Recording.2026-06-06.at.7.29.51.PM.mp4

Use of AI Tools

Copilot CLI was used to help identify the affected code paths, draft the implementation and generate tests. Each generated code was reviewed and verified manually.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: i-am-chitti <iamchitti@git.wordpress.org>
Co-authored-by: aaronrobertshaw <aaronrobertshaw@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

• Required label: Any label starting with [Type].
• Labels found: .

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.