Global Styles: Resolve per-level heading element styles in block inspector controls

[andrewserong]

Part of:

• Displaying Global Styles element inheritance #80438

Follows:

• Block Editor: Reflect inherited Global Styles values in block inspector controls #77894

What?

Resolve per-level heading element styles in the block inspector style inheritance logic.

Note: I haven't touched link styles yet as I'm trying to keep this fairly contained while getting up to speed on the feature.

Why?

The was a noted gap in the big global styles inheritance PR and an intended follow-up. It allows Heading blocks (or those that use heading elements) to more accurately reflect inherited colors and styles in the block inspector sidebar, i.e. those values that are set at an individual heading level in global styles (e.g. h2) rather than at the root (heading) level.

How?

Basically, attempt to implement the ideas that Aaron raised in #80438 for adding in this elements layer. Any errors in the approach here are likely mine as I attempt to get up to speed with how this is hooked together. Broadly:

• Move the logic where we're defining the element layers into block-editor/.../global-styles so that the global-styles-engine accepts elements as a prop (it's up to the caller to specify for the different blocks)
• Grab the headingLevel from block attributes (via the clientId retrieved from blockEdit context) so that we can grab the right element layers to pass along to resolveStyle — in my mind this is the main "bit" of this PR as it's where we tell the resolver which heading level we're using for this particular block
• Over in the global styles engine, update the resolveStyle context object to accept an elements array so that the caller can pass in a low-to-high hierarchy of elements used by the block. While this is different to the other props, in that it's an array instead of a single value, I think it has to be an array because for headings we have heading and a specific heading value like h2

Testing Instructions

To be thorough, test with the following core blocks:

• Button (core/button) — make sure this one works as in trunk

Heading blocks:

• Heading (core/heading)
• Post Title (core/post-title)
• Site Title (core/site-title)
• Query Title (core/query-title)
• Comments Title (core/comments-title)
• Term Name (core/term-name)
• Site Tagline (core/site-tagline)

1. In global styles, go to the Typography section > Headings and select a particular heading level (e.g. h2)
2. Give it some styles that look pretty obvious and save
3. In the block editor try adding the above blocks and be sure to select the appropriate heading level for them (e.g. h2)
4. Check that the styles you applied in global styles flow through to the block inspector controls
5. Note that styles set at the block level in global styles should take precedence over elements styles, so if your theme already sets block-level styles, then you might not see the elements styles
6. If you go to manually set values at the block level within post content (i.e. in the block inspector) then they should overwrite global styles values just as in the previous big PR that introduced this feature

Screenshots or screencast

Setting some styling rules at the numbered heading level in Global Styles > Headings elements > Typography

Then, when you're in a post and you add a heading block of the appropriate level, the controls should pick up that inherited value (they don't on trunk):

2026-07-21.14.49.45.mp4

Use of AI Tools

Claude Code

[github-actions]

Size Change: +326 B (0%)

Total Size: 7.75 MB

📦 View Changed

Filename	Size	Change
build/scripts/block-editor/index.min.js	427 kB	+330 B (+0.08%)
build/scripts/block-library/index.min.js	354 kB	+3 B (0%)
build/scripts/edit-site/index.min.js	304 kB	-14 B (0%)
build/scripts/editor/index.min.js	500 kB	+7 B (0%)

_{compressed-size-action}

[github-actions]

Flaky tests detected in f1a60ff.
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/29889956803
📝 Reported issues:

• [Flaky Test] Should insert content using the global inserter #78924 in /test/e2e/specs/widgets/editing-widgets.spec.js
• [Flaky Test] activate block theme when live previewing from sidebar save button #64737 in /test/e2e/specs/site-editor/activate-theme.spec.js

[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: andrewserong <andrewserong@git.wordpress.org>
Co-authored-by: ramonjd <ramonopoly@git.wordpress.org>
Co-authored-by: getdave <get_dave@git.wordpress.org>

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

[ramonjd]

I gave this a smoke test and it's working really well for top level elements. Also checked:

• buttons
• custom preset colors
• hover states inside elements
• the list of blocks in pr desc

It gets a bit weird when applying styles to elements inside blocks, e.g., Group > Elements > h2. Controls will show the top level value rather than the block's.

Not a huge deal I guess. Could be a follow up.

Thanks for getting this started! 🚀

[ramonjd]

I think core/accordion-heading is an h3. Should we add it?

https://github.com/WordPress/gutenberg/blob/fix/global-styles-element-layers/packages/block-library/src/accordion/block.json#L77

[andrewserong]

I think the accordion one might need a little more work, but I'll double-check tomorrow. Thanks for taking this for a spin!

[andrewserong]

I got it working for the accordion heading: it needed different handling as it derives its heading level via context rather than it being set on the individual accordion heading (so that all accordion headings in the set of accordion items receive the same heading level). It's a bit hard-coded and possibly smelly, but I tried to keep it neat where I could. Let me know if you think it's too much, and we can roll back and look at it in a follow-up if need be.

I'm a little on the fence about all this hard-coding, but at least it's fairly internal for now, and we could always look at improving it in the future... in any case, here's how it's looking now, inheriting the heading element style:

[ramonjd]

I'm a little on the fence about all this hard-coding, but at least it's fairly internal for now

Nice! I think it's okay. Is there an alternative in code?

My 2c is that this small fix makes headings consistent, and therefore better for the user. That to me is more important.

[andrewserong]

Nice! I think it's okay. Is there an alternative in code?
My 2c is that this small fix makes headings consistent, and therefore better for the user. That to me is more important.

Same here. I think I was just musing out loud about the idea that at some point we might codify this in block.json in some way and make it a bit more API-ey than hard-coded.

But agreed — for now I think focusing on improving the UX while keeping the code fairly self-contained is likely the right path forward.

I haven't looked at an alternative in code, mostly I wanted to confidence check that we're okay with the hard-coding. It seems we both are for now 😄

[ramonjd]

So we only getting layers from styles.elements so the resolver doesn't know about block's ancestors.

So changes to styles.blocks['core/group'].elements.h2 will show the inherited style it knows about, not the one that is applied.

I suspect it could get rabbit holey. Not sure.

[andrewserong]

So we only getting layers from styles.elements so the resolver doesn't know about block's ancestors.

Yeah, that's a limitation of the current approach for sure. Not sure how well it'll work to walk up the block hierarchy to see what's there 🤔

Will poke at the idea tomorrow and make a call on whether we should go down the rabbithole now, or defer it to a future voyage!

[andrewserong]

whether we should go down the rabbithole now, or defer it to a future voyage!

It is looking a bit hairy performing block lookups up the block hierarchy to make sure we're inheriting things correctly. My vote would be to leave blocks-within-blocks behaviour to a follow up and mark it as a task in the linked issue. What do you reckon?

[ramonjd]

Agree. A follow up sounds best. Thanks for digging in.

[getdave]

I manually tested an number of scenarios and this worked as expected.

Noting @ramonjd's feedback about ancestor styles which will need to be resolved either here or in a follow up - will this be tracked somewhere?

As noted elsewhere I think we need some UI explanation about inherited styles other than a dotted line 😅 but I appreciate that's still in the works.

Great work here - this feature is a big win for the Editor 👏

[ramonjd]

As noted elsewhere I think we need some UI explanation about inherited styles other than a dotted line

Thanks @getdave. There are things coming out of the sausage factory on this point.

Some suggested visual tweaks to the icons (#77894 (comment) and #80506).

Aaron had a crack at tooltips, but I think that needs more attention in the next cycle as well as figuring out the trade off between UX and the components/design systems.

[andrewserong]

+1 thanks for taking a look, Dave!

feedback about ancestor styles which will need to be resolved either here or in a follow up - will this be tracked somewhere?

Agreed this should be looked into. My vote is to leave it for a follow-up and for us use the linked issue #80438 to track it. My gut feeling is that for 7.1 we won't have perfect coverage here, and I think the task will be to improve how this works iteratively across small PRs and see at what point the coverage feels "good enough".

Which means, for now, is the coverage in this PR a good step forward, or does it feel too gappy?

[ramonjd]

• Top level element values flow through to the inspector controls as advertised
• Switching heading levels updates the swatches
• Block-level global styles still win over element styles

As mentioned supporting paths like Group block > elements > h2 would be a nice follow up but I don't think it's a blocker here.

Nice work 🚀

LGTM ✅

[ramonjd]

Needs a #80495 link I think

[andrewserong]

Added the PR to a separate changelog entry. I left the existing entries alone just in case it affects branch conflicts when we go to backport this (but I might be overthinking this one 😄)

[ramonjd]

Can be later, but you do you think a test with { level: 2 } (or one with { level: 0 }) would catch a future regression in the path between useVariationAndElements and getElementLayers.

[andrewserong]

We've already got a level: 2 so I've added one with level: 0, good catch!

[andrewserong]

As mentioned supporting paths like Group block > elements > h2 would be a nice follow up but I don't think it's a blocker here.

Cheers! Yes, let's take a look in a follow-up and I'll jot down some notes in the linked issue.

Thanks for the reviews! I'll merge this in once tests pass

[github-actions]

I just cherry-picked this PR to the wp/7.1 branch to get it included in the next release: 26b39c0

[t-hamano]

Sharing for visibility; I'm considering removing the UI for global style inheritance from WP 7.1 and GB 23.6 releases, although it is not yet finalized. Please refer to #77894 (comment) for details.

[andrewserong]

Sharing for visibility; I'm considering removing the UI for global style inheritance from WP 7.1 and GB 23.6 releases, although it is not yet finalized. Please refer to #77894 (comment) for details.

Oh, thanks for the heads-up @t-hamano! Do you want me to hold off on working on fixes like this for now? (My main interest is just in helping out with whatever's going to help with the release — whether that's trying to stabilize or fix things, or get out of your way 😄)

[t-hamano]

I'm considering introducing the Gutenberg plugin check as I do not want to stop continuous development.

See #77894 (comment)

[t-hamano]

I just cherry-picked this PR to the release/23.6 branch to get it included in the next release: 6cd4ef0