Size Change: +2.99 kB (+0.04%)

Total Size: 6.89 MB

_{compressed-size-action}

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:

• background.gradient (or background.backgroundImage)
• background.backgroundClip: 'text'

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 state

Both 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
• Simplest implementation
• Panels always reflect the actual state

Cons
• Optional controls can suddenly appear in the background panel as a side effect of something the user did in the color panel. That feels disconnected from the action that caused it.

Option 2: Hide gradient when a text gradient is active

If backgroundClip === 'text', the gradient control is hidden from the background panel.

Pros
• Clear separation between text gradient styling and background styling

Cons
• If a user is working in the background panel and transitions into a text gradient state, the control they were just using disappears mid workflow. In testing this felt abrupt and confusing.

Option 3: Smart hasValue handling

Treat the text-gradient combination as “no value” for the background panel controls so they do not auto show.

Pros
• Prevents controls appearing automatically due to state created elsewhere

Cons
• The disappearing control problem still exists. Controls can vanish during interaction which felt worse than simply exposing the state.

Option 4: Smart hasValue plus smart reset behavior

Same as option 3 but with reset logic that preserves the text gradient when reset is triggered from the background panel.

Pros
• Avoids accidentally clearing the text gradient

Cons
• “Reset all” no longer truly resets the state the panel appears responsible for, which makes the behavior harder to reason about.

Option 5: Disable background controls when text gradients are supported

Another possible direction was to disable the background gradient and clip controls entirely when text gradient support is present.

Pros
• Very clean separation between the text styling system and the background system

Cons
• This removes flexibility that already exists in the background support feature set. Theme authors and advanced users may intentionally combine these values in ways that are not strictly part of the text gradient feature.

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.
• When text gradient support is active, the background clip control filters out the text value.
• The gradient control in the background panel remains available but does not auto show just because the gradient is currently being used for text.
• The color panel owns the text gradient flow (background.gradient together with background.backgroundClip: 'text').
• The background panel owns the non text background clip and gradient usage.

Reset behavior follows the same ownership model.
• The color panel reset clears the text gradient combination when backgroundClip === 'text'.
• The background panel reset clears gradient and clip values only when the clip is not text.

Why the background controls are still present

Even 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.

Result

This 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.

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)

Regarding 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.

Flaky tests detected in 5de5cb0.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/22833658675
📝 Reported issues:

• [Flaky Test] Custom Completer: should allow newlines after multiple option completions #48535 in /test/e2e/specs/editor/various/autocomplete-and-mentions.spec.js
• [Flaky Test] should insert elements from multiple completers in a single block #47916 in /test/e2e/specs/editor/various/autocomplete-and-mentions.spec.js

I just want to validate, from a glance, that this direction looks good to me, thanks for working on it!

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:

• Block Supports: Add background gradient support that can combine with background images #75859
• Block Supports: Add background clip support and combined UI for text gradient selection #76171
• Block Supports: Add background.color support and refactor foreground and background panels #76474

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.

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.

I've just found time to digest this.

The separate ownership option (6) makes sense to me:

1. Color panel owns the text gradient combination
2. Background panel owns everything else

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.

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.

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 background statement.

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: