Block Supports: Add background.color support and refactor foreground and background panels#76474
Draft
aaronrobertshaw wants to merge 13 commits into
Draft
Conversation
- Add background.gradient to block.json and theme.json schemas - Add STYLE_PROPERTY entry (backgroundGradient) in constants.js - Add gradient to VALID_SETTINGS, VALID_STYLES, PROPERTIES_METADATA, INDIRECT_PROPERTIES_METADATA, and APPEARANCE_TOOLS_OPT_INS in class-wp-theme-json-gutenberg.php - Enable gradient globally in lib/theme.json - Add gradient setting in global-styles-engine get-setting.ts
- Add gradient property to BackgroundStyle type definition - Update JS style engine to combine gradient and backgroundImage into a comma-separated background-image CSS value - Add gradient definition to PHP style engine class - Update compute_style_properties in class-wp-theme-json-gutenberg.php to collect both gradient and backgroundImage before passing to the style engine for combined background-image CSS output
- Update background.php render support to handle gradient values, including combined gradient + background image - Add safecss_filter_attr_allow_css filter in kses.php to allow combined gradient+url() background-image values that WordPress core safecss_filter_attr() strips
- Add gradient picker to background-panel.js using ColorPanelDropdown with preset slug encoding/decoding - Suppress color panel gradient tab when background.gradient is enabled to avoid duplicate gradient UIs (color-panel.js) - Update hooks.js to preserve gradient presets for blocks with background.gradient support and disable gradient settings for blocks without support - Add gradient detection in background.js and useBlockSettings in utils.js - Add background panel SCSS styles with hasInnerWrapper pattern - Add slot className for inner wrapper in styles-tab.js and block-inspector/index.js
- Opt Group block into background.gradient in block.json - Update core-blocks.md and theme-json-living.md documentation
- PHP: background block support tests for gradient rendering - PHP: theme-json tests for gradient in compute_style_properties, remove_insecure_properties, and appearance tools opt-in - PHP: style engine tests for gradient CSS generation - JS: style engine tests for gradient and combined gradient+image
The gradient pattern in gutenberg_allow_background_image_combined only matched rgb()/rgba() inside gradient functions. Gradients using hsl(), oklch(), lab(), or other color functions with parentheses were stripped when combined with a url() background image. Broaden the nested parenthesis pattern to allow any single-level nested parens, covering all CSS color functions. Add KSES tests to the background block support test suite verifying combined gradient and url() values survive safecss_filter_attr() across color formats.
…class Replace the gradient control's per-item border workaround and the image control's inline border with a reusable `.block-editor-background-panel__item` class that handles grouped border and radius styling for all panel items.
aaronrobertshaw
added
[Type] Enhancement
github-actions
Bot
added
[Package] Blocks
|
Size Change: +258 B (0%) Total Size: 6.89 MB
ℹ️ View Unchanged
|
Member
|
I know this is early days, but the direction is promising. Thanks for putting so much thought into the technical side of things. 
The separation of concerns, i.e., foreground === what's on or applied to content, and background === the canvas behind it, for me is conceptually clean. Seems scalable too. I think we can debate it later, I only wanted to raise the question of terminology and how users might make the link between "foreground" and text. "Foreground" makes sense to me if you're thinking like a designer or a CSS mental model, just wondering if users looking to change their text color might be confused. Could be a matter of just changing it to I'm not sure! |
Contributor
Good thoughts, and it actually surfaces fresh 
All those are existing shortcomings that have built up over time, they are emerging now thanks to these explorations, which I regret are turning into a rabbit hole. It's not just about stacked layers of color/gradient/image across text and backgrounds both, it's about how we use tabs, in some cases for those, in other cases for pseudo states. I quickly explored an alternative to see if the foreground/background separation could remain, but in single panel, like Dimensions: 
But it falls apart too. Assuming you'll be able to set a text gradient, should you not be able to do that for link too? How about Hover? The IA unfortunately starts crumbling a bit. At this point, before you dive much deeper down the separation of panels, this deserves a design decision and a mockup that accounts for these details. Here's a starting point, but it gets out there: 
Where I think this shows potential:
What needs more work is figuring out how we can allow layered color/gradient/image fills for each item. Shown using an accordion-behaving panel, but it's huge. |
Contributor
Author
|
Thanks for the expertise and explorations here @jasmussen 🙇 For anyone else following along, the work in the following PRs, including this one, likely need a general direction to be settled on before we can progress them much further:
Depending on general confidence in the UI, we could look to land the first two PRs above with the view to iterate on them quickly. |
This was referenced Mar 15, 2026
Draft
aaronrobertshaw
force-pushed
the
update/text-gradient-ui-on-gradient
branch
from
5de5cb0 to
5ec7d18
Compare
Contributor
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What?
Follow up to #76171 and #75859.
Adds a new
background.colorblock support, renames the Color panel to "Foreground", and restructures the controls across the Foreground and Background panels to create clearer separation of concerns.Why?
As discussed in #76171, the current Color panel mixes foreground and background concerns. The "Background" control (a color swatch) lives inside the "Color" panel, while background images and gradients have their own separate "Background" panel. This creates a confusing taxonomy where related background tools are split across panels.
Additionally, the existing
color.backgroundsupport generates the CSSbackgroundshorthand property, which has caused conflicts with other background features likebackground-imageandbackground-clip. By introducing a newbackground.colorsupport that generatesbackground-color(the longhand CSS property), we sidestep backward compatibility concerns, mirroring the approach taken forbackground.gradientin #76171.This PR implements the "separate panels" design direction proposed by @jasmussen, where Foreground and Background panels each own their respective controls, with a path toward future features like layered or ordered backgrounds, gradients, images etc.
How?
New
background.colorblock supportbackground.colorrule that generatesbackground-colorCSS, with support for color preset CSS custom properties.backgroundSolidColorentry mapping['background', 'color']to the style property registry.useSettingsForBlockElementto explicitly enable background settings (color,gradient,backgroundClip) when a block declares support, since these features may not have corresponding global/theme settings.gutenberg_render_background_supportto handlebackground.colorserialization and thehas-backgroundclass.Panel restructuring
ColorToolsPaneldefault label).ColorPanelDropdown, with encode/decode helpers for preset slug references.color.backgroundfrom the Foreground panel whenbackground.coloris active, preventing duplicate controls.Paragraph block adoption
background.color(withcolor: trueas a default control) and opted out ofcolor.background("background": false).Testing Instructions
background-clip: textand-webkit-text-fill-color: transparent.Testing Instructions for Keyboard
Screenshots or screencast
Screen.Recording.2026-03-13.at.12.59.40.am.mp4