Global Styles: filter and indicate blocks that have custom styles

[ramonjd]

What?

Closes #81316

Relies on, but is not blocked by #81407

Marks blocks that have user styles in Styles → Blocks with a changeset list, and adds a menu to filter the list down to just those blocks.

Why?

The list shows every registered block with nothing distinguishing the ones you have styled, so reviewing your own customizations means opening blocks one at a time.

How?

Dots, Gandalf. Dots.

Testing Instructions

1. Open the Site Editor → Styles → Blocks. No dot, since nothing is customized yet.
2. Open Quote, set a text color, go back. The Quote row now has a dot.
3. Open the funnel menu beside the search field, choose Customized. Only dotted rows remain.
4. Type quo in the search field while filtered. Search and filter compose.
5. Clear the search, open Quote, reset the text color, go back. The dot is gone!
6. Set a block-specific color palette on any block (Blocks → block → Colors → palette). That block gets a dot too.

Testing Instructions for Keyboard

1. Tab to the funnel button beside the search field, open it with Enter or Space, and move between All blocks and Customized with the arrow keys. The checked option is announced.
2. With a screen reader on, tab through the list: rows for customized blocks announce "Has custom styles" after the block name.

Screenshots or screencast

With dot (previous attempt, now reinstated)

Kapture.2026-08-10.at.18.32.12.mp4

With changeset list (tried and rolled back)

Kapture.2026-08-11.at.12.38.10.mp4

Use of AI Tools

Authored with Claude Code. The design, scope decisions, and review rulings are mine; the implementation was written by the tool under review and I have verified it manually in the editor.

[github-actions]

Size Change: +1.39 kB (+0.02%)

Total Size: 7.73 MB

📦 View Changed

Filename	Size	Change
build/scripts/edit-site/index.min.js	335 kB	+325 B (+0.1%)
build/scripts/editor/index.min.js	531 kB	+567 B (+0.11%)
build/styles/edit-site/style-rtl.css	21.8 kB	+65 B (+0.3%)
build/styles/edit-site/style-rtl.min.css	17.9 kB	+61 B (+0.34%)
build/styles/edit-site/style.css	21.8 kB	+64 B (+0.29%)
build/styles/edit-site/style.min.css	17.9 kB	+59 B (+0.33%)
build/styles/editor/style-rtl.css	31.9 kB	+65 B (+0.2%)
build/styles/editor/style-rtl.min.css	27.2 kB	+61 B (+0.22%)
build/styles/editor/style.css	32 kB	+66 B (+0.21%)
build/styles/editor/style.min.css	27.2 kB	+61 B (+0.22%)

_{compressed-size-action}

[andrewserong]

This is a great start! Not necessarily for now if you're just getting a proof of concept up for discussion, but some quick notes while I tested it out:

With the filter button in there now, should we use the shorter variant for the search field? Currently they look a little mismatched:

For reference, here's the search field in the Pages screen:

---

Otherwise the filtering is working well for me 👍, a couple of observations

• With a filter applied and no customisations made the empty state is a little bare (i.e. maybe we could tweak the "no blocks found" language when a filter is active?)

• With the blue dot indicator active I really wanted to be able to either reset the changes to a particular block and/or see at a glance what the block had customised. So I expected the dot to either be a button, have a tooltip, or both.

---

In case it isn't obvious, I'm really excited about this feature, it feels very much needed as I find the blocks list in global styles can be pretty impenetrable / very easy for things to get lost.

[ramonjd]

should we use the shorter variant for the search field?

Done! Now using compact.

With the blue dot indicator active I really wanted to be able to either reset the changes to a particular block and/or see at a glance what the block had customised. So I expected the dot to either be a button, have a tooltip, or both.

I'm inclined to agree, especially if this same dot is clickable in the global styles inheritance work.

However, if the dot is confusing or will stultify momentum while we wonder what to do with a dot, I'd remove it completely.

Maybe we can revisit the dot's role as a reset button or otherwise in the next follow up, probably as a complement to some sort of summary copy too.

Or we consider, some other highlight,

or a quick follow up to use existing getGlobalStylesChanges() to show a summary of the changes?

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

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

[ramonjd]

or a quick follow up to use existing getGlobalStylesChanges() to show a summary of the changes?

I'll do this in this PR for now. It also removes an accessibility issue that's causing test fails. We have time to iterate here I think. Thank you!

[ramonjd]

This PR adds missing styles to the changelist:

• Global Styles: report border, shadow, outline, filter and dimension changes #81407

[ramonjd]

Just to mention where we can go with this...

A next iteration could show pills and add further filters:

An alternative (until we decide to add anything else) is make a custom filter toggle:

[Copilot]

Pull request overview

Adds indicators and filtering for customized blocks in Global Styles.

Changes:

• Detects user block styles/settings and summarizes changes.
• Adds a Customized filter with accessible result announcements.
• Exports the Global Styles changelist utility and adds tests.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
test/e2e/specs/site-editor/push-to-global-styles.spec.js	Updates block-row selection for summaries.
packages/global-styles-ui/src/test/screen-block-list.js	Tests customization detection and summaries.
packages/global-styles-ui/src/style.scss	Styles filtering and summary UI.
packages/global-styles-ui/src/screen-block-list.tsx	Implements summaries and filtering.
packages/global-styles-ui/CHANGELOG.md	Records the enhancement.
packages/global-styles-engine/src/index.ts	Exports the changelist utility.
packages/global-styles-engine/CHANGELOG.md	Documents the new export.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[ramonjd]

No, not like this. Add random text here is not a good idea.

• Global Styles: report custom CSS changes in the changelist #81741

[github-actions]

Flaky tests detected in 06a1b96.
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/32092134091
📝 Reported tests:

should insert media, convert to blocks, and undo in one step in /test/e2e/specs/editor/blocks/classic.spec.js, passed after 1 failed attempt.

TimeoutError: locator.click: Timeout 10000ms exceeded.
Call log:
  - waiting for locator('role=toolbar[name="Block tools"i]').locator('role=button[name="Convert to blocks"]')

    at Editor.clickBlockToolbarButton (/home/runner/work/gutenberg/gutenberg/packages/e2e-test-utils-playwright/src/editor/click-block-toolbar-button.ts:17:15)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/blocks/classic.spec.js:98:3

[jasmussen]

Nice tinkering! I'd avoid the left border highlight, in the admin it's still used as a focus style.

I'd love to get broader feedback on this PR both by folks already pinged, perhaps also by @WordPress/gutenberg-design. As-is, either of these can honestly work for me:

• The list version is very glanceable.
• The dot version relies on the multi-entity saving piece or another interface to list actual changes, but is also a clean way of indicating: this block has something.

In both cases, they are very list focused, however. As noted, that can work, though I did imagine the actual changeset would be shown not in the list of blocks, but on the drilldown of each block individually. E.g. somewhere here:

Below the image might get jumpy as it causes layout shifts for any change you make. But certainly there could be a list here, somewhere. And if it's inside "Advanced", then it could be available both in global styles, and locally for any locak blocks changed. Useful for the style inheritance piece, though perhaps "advanced" placement is not discoverable in global styles unless also paired with the blue dot, either on the Advanced panel itself, the list as you tried, or both.

None of that is necessarily feedback that goes in a different direction than this: I'll defer to input from others. And perhaps we can get some feedback from my friend @beafialho, as she has worked a lot with block styles and can help explain where this information might be useful.

[beafialho]

Nice!

The dot version seems to me like the cleanest and clearest indication that there have been customisations to the block, I've seen that treatment across multiple digital tools and platforms. I have doubts about changeset list because it adds a lot of visual noise and if there are a lot of customisations most of them aren't visible anyway.

[andrewserong]

The dot version seems to me like the cleanest and clearest indication that there have been customisations to the block, I've seen that treatment across multiple digital tools and platforms.

I agree. I think from the Block list view the main thing I'd want to see is "which blocks have I customised" rather than a list of what has been customised within it, and so I quite like the dot idea, too. It also seems like it might be a good first step and we could then look at where and how we expose lists of what's been customised (along with block-level reset all changes) in follow-ups?

That said, very cool that it works to be able to list things in the block list view. Either way, I'm in favour of this feature, as I think it'll be a big improvement for how we use global styles.

[ramonjd]

Thanks for the feedback folks. I can revert back to the dots, sounds like it's the preferred approach. I agree it will make things more compact, and it was worth a shot to see what the summary looks like.

There were concerns about a static dot that is unclickable. Furthermore, that the dotty UI will be, for a time, inconsistent with global styles inheritance UI.

I would like to dismiss those concerns temporarily, get this PR merged, and iterate when those concerns become concrete. We're at the start of the cycle so I think we can afford to.

[andrewserong]

I would like to dismiss those concern temporarily, get this PR merged, and iterate when those concerns become concrete. We're at the start of the cycle so I think we can afford to.

💯 I think getting the PR merged with dots in place will make it easier to explore our options in subsequent PRs. Thanks for the persistence here!

[ramonjd]

Dots are back on the menu!

[andrewserong]

This is testing really well for me in block the global styles sidebars, just left a couple of nits/thoughts but nothing blocking, I reckon we should land this! Also, nice update for the empty state 👍

On the topic of follow-ups to look at how we display a list of what's been customised, I think it'll be good stuff to dig into because in some cases it can be really hard to find what you changed, especially if it winds up being within a style variation. E.g. here I'm trying to find the color change I'd made to the Outline variation of the Button block:

2026-08-18.11.33.30.mp4

That problem kind of touches upon the bigger picture stuff of how we indicate changes within the sidebar, though, so a much bigger can of worms 😄

This LGTM! 🚀

[andrewserong]

Not for now, but potentially a refactor idea: this currently places the check of whether or not to render within BlockMenuItem rather than further up the hierarchy where we show an empty state. So, it's theoretically possible (but unlikely) to have a situation where the list renders completely empty (because every item in the list returns false for this check) rather than show the empty state text.

So, at some point, we might want the check to occur at the same place where we do the filtering. Just a thought for later, nothing blocking for now!

[ramonjd]

Good point. Hoisting might change a few files, so I'll do it a follow up. 👍🏻

[ramonjd]

On the topic of follow-ups to look at how we display a list of what's been customised, I think it'll be good stuff to dig into because in some cases it can be really hard to find what you changed, especially if it winds up being within a style variation.

100% Wondering if it might overlap with the global style inheritance paths that @aaronrobertshaw was looking at 🤔

Thank you for testing!

[aaronrobertshaw]

100% Wondering if it might overlap with the global style inheritance paths that @aaronrobertshaw was looking at 🤔

The early iterations of displaying inherited global styles was for block instances only. User edits over the theme's or core's global styles were really in scope.

The main difference that might keep these separate though was the block instance's inheritance resolution has to take into account the cascade from multiple sources. In this case, it appears more just is there a value within this specific node.

Given that, I'd say it would only be the UI affordances that we actually settle on for the display of inherited styles that would be directly applicable here.