Editor: Add a background clip block support to facilitate text gradients

[aaronrobertshaw]

Backport of Gutenberg PR WordPress/gutenberg#77141

Trac ticket: https://core.trac.wordpress.org/ticket/66094

Adds a background.backgroundClip block support, so a block can set which box its background is painted into: border-box, padding-box, content-box, or the text itself. Clipping to the text is what gives blocks a gradient text fill.

This PR backports:

• the backgroundClip definition and its value parser in WP_Style_Engine,
• gradient classnames moving to a classnames_func callback there, which keeps the file in sync with Gutenberg. Behaviour is unchanged,
• the background.backgroundClip setting and style in WP_Theme_JSON, its CSS property mapping, and the vendor prefixed declarations that go with it,
• background-clip and its vendor prefixed companions added to the KSES safe style allowlist,
• the has-background class being skipped when the background is clipped to the text,
• and the accompanying style engine and background block support tests.

For the text value the engine also emits -webkit-background-clip and -webkit-text-fill-color. For the box values only the fill color is reset, because -webkit-background-clip is an alias of background-clip in Chromium and resetting it would discard the value set above.

The editor controls, and the core/heading and core/paragraph opt-ins, arrive with the next Gutenberg package update.

Testing instructions

No block opts in yet and there is no control in the editor, so test the generated global styles.

1. Add this to a block theme's theme.json:

"styles": {
	"blocks": {
		"core/heading": {
			"background": {
				"gradient": "linear-gradient(to right,#ff0000,#0000ff)",
				"backgroundClip": "text"
			}
		},
		"core/group": {
			"background": {
				"gradient": "linear-gradient(to right,#ff0000,#0000ff)",
				"backgroundClip": "content-box"
			}
		}
	}
}

2. Load a page with a Heading and a Group and check the global styles. They should contain:

:root :where(.wp-block-heading){background-image: linear-gradient(to right,#ff0000,#0000ff);background-clip: text;-webkit-background-clip: text;-webkit-text-fill-color: transparent;}
:root :where(.wp-block-group){background-image: linear-gradient(to right,#ff0000,#0000ff);background-clip: content-box;-webkit-text-fill-color: unset;}

3. The heading should render with the gradient on its letters. Give the group padding and a thick dashed border, and its gradient should stop at the inner edge of the padding.

Without the change neither background-clip declaration is generated, so both render as a plain background gradient filling the whole block.

Use of AI

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5
Used for: the mechanical port and polishing this description

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.