Block Supports: Add background clip support and combined UI for text gradient selection#76171
Draft
aaronrobertshaw wants to merge 3 commits into
Draft
Block Supports: Add background clip support and combined UI for text gradient selection#76171aaronrobertshaw wants to merge 3 commits into
aaronrobertshaw wants to merge 3 commits into
Conversation
aaronrobertshaw
added
[Type] Enhancement
github-actions
Bot
added
[Package] Blocks
|
Size Change: +2.97 kB (+0.04%) Total Size: 7.74 MB 📦 View Changed
ℹ️ View Unchanged
|
1 task
Contributor
Author
|
Quick update, as there's been a lot of exploration here but a perfect solution has been hard to come by. The explorations have mostly focused on how the background panel should behave when text gradients are supported. The complication here is that a text gradient is not a separate setting. It is composed from two background support values:
The color panel's text gradient control sets both of those values. The background panel also exposes controls for gradient and background clip. That means two different panels can manipulate the same underlying data. Because of that overlap, I explored several approaches: Option 1: Fully transparent shared stateBoth panels simply reflect the raw underlying values. If a text gradient is active, the background panel shows whatever those values imply. That means the gradient control may appear with a value and the clip control may show text. Pros Cons Option 2: Hide gradient when a text gradient is activeIf backgroundClip === 'text', the gradient control is hidden from the background panel. Pros Cons Option 3: Smart hasValue handlingTreat the text-gradient combination as “no value” for the background panel controls so they do not auto show. Pros Cons Option 4: Smart hasValue plus smart reset behaviorSame as option 3 but with reset logic that preserves the text gradient when reset is triggered from the background panel. Pros Cons Option 5: Disable background controls when text gradients are supportedAnother possible direction was to disable the background gradient and clip controls entirely when text gradient support is present. Pros Cons Because the background support APIs already allow these combinations, removing the controls would effectively reduce capabilities that currently exist. Option 6: Separate ownership (The chosen option)The approach that seemed to provide the best balance is to separate ownership of the shared values. The key idea is that each panel should primarily manage the state it conceptually owns rather than both panels trying to co own the text gradient configuration. This results in the following behavior. Reset behavior follows the same ownership model. Why the background controls are still presentEven when text gradient support exists, the background gradient and clip controls are still exposed because those features already exist independently of text gradients. The goal was to avoid removing flexibility that theme authors or advanced users might rely on while still keeping the text gradient workflow anchored in the color panel where it is introduced. ResultThis approach avoids controls appearing or disappearing unexpectedly while still preserving the full flexibility of the background support system. It also keeps reset behavior predictable and keeps the text gradient workflow centered in the color panel where users would expect to find it. |
aaronrobertshaw
force-pushed
the
try/background-gradient-support
branch
from
March 8, 2026 02:20
272f719 to
895fab7
Compare
aaronrobertshaw
force-pushed
the
update/text-gradient-ui-on-gradient
branch
from
March 8, 2026 02:23
80cdd52 to
7c6702f
Compare
Contributor
Author
|
There's still a long way to go but I ironed out a few kinks here over the weekend. I'm not suggesting the UX is perfect only that this PR now provides something tangible that people can play with and see how it truly feels. Hopefully, this will spark some further ideas or help us coalesce around an ideal path forward. Here's a quick glimpse at the latest state (also added to PR description) TextGradient.mp4Regarding all the test failures, I'll get to those early next week. For now, I just wanted to be able to move the UX discussion forward. |
aaronrobertshaw
force-pushed
the
update/text-gradient-ui-on-gradient
branch
from
March 8, 2026 21:33
7c6702f to
cd7e90b
Compare
|
Flaky tests detected in c4e53c5. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/24182734942
|
Contributor
|
I just want to validate, from a glance, that this direction looks good to me, thanks for working on it! |
Contributor
Author
|
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. |
Member
I've just found time to digest this. The separate ownership option (6) makes sense to me:
Reset behavior follows the same separation, right? Sounds clean and predictable. Just to confirm what happens when a user changes the clip dropdown in the background panel from text to border-box (or any other value) while a text gradient is active. Is that even possible? I'm understanding that the gradient value carries over to the background fill? Anyway, I think you've made the right trade offs. |
Contributor
I appreciate yet again the patience, the exploratory work. The value of these gradients is extremely real, and worth landing in some shape or form as soon as we can. So we need both a near term and a long term plan for this. It all relates to what I oultined here as well, we have built up a complex IA of dependencies, where a mix of color-adjacent things live as Items in an ItemGroup, based on the limitation that background is one thing and color is another. In fact we may decide that to remain the correct path forward, separating concerns, and lessening the focus we've had on layering where a "solid" can be a part of a But it is worth mapping out, so we reach all the corners, including the one where you might want an animated gradient on link-hover. We either plan for that to become a possibility to grow into, through the right IA from the start, or we cauterize that opportunity from the start. Both are valid, and I will connect with some designer folks for a chat this week so we can plot this out. Ideally we also end up with an answer to this: 
|
This was referenced Mar 16, 2026
aaronrobertshaw
force-pushed
the
try/background-gradient-support
branch
from
March 28, 2026 01:42
0567753 to
92d1b99
Compare
aaronrobertshaw
force-pushed
the
update/text-gradient-ui-on-gradient
branch
from
April 8, 2026 09:13
5de5cb0 to
5ec7d18
Compare
Contributor
Author
|
I've rebased this but some of the conflicts were a bit gnarly, so hopefully this is still testing as advertised. The PR refactoring the background and color panels that was based on this (#76474) still needs updating but I'll have to finish that off tomorrow. Additionally, the new plan is that I'll split this PR up so that the background clip block support can be merged without an UI updates or changes. This would mean the underlying block support we need for text gradients can land but would only be available via Global Styles, theme.json, or hard coded block attribute values. This should buy some additional time to narrow in on the ideal UX. |
Contributor
Author
|
This PR has been split up into the following:
Once they are ready for review and tested more thoroughly, I'll close this PR so we can move ahead incrementally with them. |
Contributor
Author
|
After bouncing around some ideas and potential paths forward, in particular in a chat with @ramonjd, I think our best bet to not introduce too many rough edges is to actually proceed with the text gradient as a fully formed feature. I propose:
The result of this is that we can offer the text gradient feature while still hiding the background clip control until we refine the UI further. If theme authors really wish to enable and use the background clipping UI they can do. The likelihood of this is very small, though, as non-text-gradient background clipping would be an extremely nice use case. I've pushed these changes but have run out of time so will test more thoroughly tomorrow and record a few demos to illustrate how this works in practice. |
Contributor
Author
|
Following on from my previous comment, I've now had a chance to test and capture the current state of the PR. Default behaviour (background clip UI hidden) Screen.Recording.2026-04-10.at.3.07.42.pm.mp4With the background clip UI explicitly opted in via theme.json Screen.Recording.2026-04-10.at.3.06.32.pm.mp4As you can see, the two gates are now independent:
This means we can ship the refined, user-facing piece (text gradients in the Text color control) whole, while keeping the rougher clip control behind a deliberate opt-in that we can iterate on between now and 7.1. The whole pipeline (block support, global styles plumbing, style engine, PHP rendering) is in place either way, so future refinement is purely UI polish on the clip control rather than another round of wiring. @jameskoster would love a soft green light to proceed on this basis. The full rationale for landing it this way rather than splitting into smaller pieces without UI is in my previous comment. Happy to keep iterating on the clip control in follow-ups once the shape of its UI is clearer. What do you think? P.S. There are also some tweaks we can make regarding the UX of exposing the |
Contributor
|
In general this seems good 👍 The only thing that's a little confusing is the interaction between Text Color and Background Color when Other than that, the Background Clip control is not clearly labeled which makes it a bit tricky to interpret until you open the popover which isn't ideal. I wonder if this should be a |
Contributor
Author
|
Appreciate the insightful feedback as always @jameskoster 🙇 We aren't in a huge rush here so I can take the time to iterate on the UI a little and see if we can land it in an improved state. |
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
4 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?
This PR builds on top of two in-progress PRs:
color.gradientwrites abackgroundCSS shorthand that conflicts withbackground-clip; having the gradient onbackground.gradientkeeps both in the same property groupIt reworks the UI and UX of background clip in the following ways.
Why?
The original background clip PR scoped the control to Global Styles only and left open questions about how clip interacts with gradient text (a common use case), how the control should look, and where it should live. This PR answers those questions.
How?
Text gradient integration in the Color panel
A gradient picker is added to the Color panel's Text section, allowing users to apply gradient text without leaving the color-focused context. This stores its value at
background.gradientwithbackgroundClip: 'text', the same properties used by the Background panel.Because both panels write to the same location, they must coordinate:
text. This lets users switch clip mode directly from the Background panel. Changing away fromtext(e.g. toborder-box) reveals the gradient control with the existing value, creating a natural "convert text gradient to background gradient" flowbackground.gradientandbackground.backgroundClipwhen the text gradient is setbackgroundClipwhen it is'text', preventing invisible text if reset is triggered while a text gradient is activehas-backgroundblock class is suppressed when the gradient is being used as a text fill, since the gradient is not painting the block's background in that caseBackground panel styling
The background panel mixes two kinds of items:
ColorPanelDropdownitems (which usestyle.scss's shared border/radius system via the__itemclass) and plainToolsPanelItemelements (background image, clip). This required targeted CSS overrides in a newbackground.scssto:Testing Instructions
Textas the active value).Screenshot
TextGradient.mp4