Block Styles: Display inherited Global Styles and own Block Style Variation styles in Block Inspector

[aaronrobertshaw]

Overall Goal

A block's inspector controls should display values inherited from Global Styles (theme.json defaults, user Global Styles edits, or the block's own style variation) as placeholder values when no local override is set. Today these inputs read empty when no local override is set, even though the block renders on canvas using a typography size, a link colour, or padding coming from the theme. Authors can see that a value is inherited (the field is empty), but they can't see what the inherited value is without opening DevTools or editing the field to reveal what comes back.

This iteration supersedes #64670 (@ramonjd's prior implementation tracking issue, now closed in favour of this one) and continues work surfaced in #37752 (user-facing request, updated August 2024 with per-control mockups from @jameskoster), #49278 (@annezazu's source-visualization design spec), and #43082 ("what does unset mean?").

Status

A proof-of-concept implementation is open in #77894 (draft). It demonstrates the inherited-value UX across typography, dimensions, colour, border, filters, and background controls so the direction can be reviewed before committing to broader component API work.

This work is stacked on #77279. That PR relocates the root-level colour controls out of the catch-all Color panel and into the panels they belong with (Text → Typography, Background + Gradient → Background, element-level colours → a new Elements panel). The inheritance display threads through those relocated panels, so #77894 is based on #77279 and should land after it.

Scope has grown since the first draft of this issue. Several source-attribution affordances originally listed as out of scope are now being prototyped inside the same PoC rather than split into follow-ups (see Scope below for the revised split):

• a local-override indicator on controls whose value overrides an inherited one;
• a "Reset to inherited value" action for those local overrides;
• a "Push to Global Styles" action for an individual local override;
• a source-layer breadcrumb in the inherited tooltip, attributing the value to the layer it resolved from — bounded to what the Global Styles data itself expresses (root / element / block-default / own-variation), not sources that can't be determined from that data (see Out of scope).

Known PoC tradeoffs (from #77894, to be resolved before merge): the override dot and inherited tooltip are currently portaled into existing control labels with createPortal, and some DOM-selector coupling is used to locate label elements. These are deliberately pragmatic for the PoC and avoid public API changes to ToolsPanelItem / BaseControl / colour + picker controls while the direction is evaluated. If the direction proceeds, a cleaner public component API for label adornments / inherited-state indicators is likely warranted.

Scope for This Release

In scope.

• Built on the relocated control layout from Block Supports: Relocate text and bg color controls to Typography and Background panels #77279: inherited values are surfaced through the Typography, Background, and Elements panels rather than the former single Color panel.
• Four inheritance layers: root, element, block-default, own-variation.
• Inspector controls that can meaningfully render an inherited value: text / number / unit inputs, preset selects, ranges, colour swatches, BoxControl, BorderBoxControl, toggles.
• Inherited value rendered as the control's at-rest placeholder/selection when no local override is set; inherited placeholders are not committed as local block styles until the author explicitly chooses them.
• Single-undo reset: clearing a local override, its preset class, and any style-path reference in one atomic attribute update.
• Correctness across the four preset serialization forms (slug string, var:preset|..., var(--wp--preset--*), raw value), and preservation of valid falsy values such as 0.
• Local-override affordances (moved in from the previous out-of-scope list, now prototyped in Block Editor: Reflect inherited Global Styles values in block inspector controls #77894): an indicator marking a control as a local override of an inherited value, a "Reset to inherited value" action, and a per-control "Push to Global Styles" action for an individual override.
• Source-layer breadcrumb in the inherited tooltip, attributing a value to the layer it resolved from — limited to what the Global Styles data expresses (root / element / block-default / own-variation).

Out of scope (tracked separately; planned follow-ups):

• Source attribution beyond the Global Styles data. The inherited tooltip already shows a breadcrumb for the layer a value resolved from within the Global Styles data (root / element / block-default / own-variation). What it does not attribute are sources that can't be determined from that data: nested / ancestor block style variations, values arriving via the DOM cascade, plugin-injected CSS, or theme.json's free-form css. Deeper attribution and the final tooltip/popover treatment are coordinated on Styles: show a hierarchy of styles clearly (theme, user, global unspecific, global specific, local, etc) #49278.
• Ancestor-variation resolution, CSS-property inheritance through the DOM cascade, plugin-injected CSS, theme.json's free-form css escape hatch.
• Multi-select inspector state, native editor, pattern overrides, block bindings as an inheritance source.
• Cross-block inheritance (e.g. "Content inherits from Paragraph's Global Styles").
• Unsetting global styles (tracked at Design tools: Better handling of unset / inherited values #43082).

Carried over from #64670. The scope constraint and the resolution hierarchy @ramonjd brainstormed there carry forward verbatim (see Approach). Nothing shipped from #64670's attempted PRs: #55952 closed unmerged, and #59929 closed unmerged too, but its settings[globalStylesDataKey] pattern has since landed via #61556 and is what this iteration reads from.

Outcome. The inspector stops hiding the inherited value. Authors can see at a glance what a block will render even when they haven't set anything locally, and can tell a local override apart from an inherited value. Delivered on top of #77279; currently a proof of concept (#77894) pending design and technical review. No experiment flag. No staged rollout.

Approach

A block's inspector panel receives two value objects:

1. Local value. The block's attributes today, unchanged.
2. Inherited value. The same shape, populated from merged Global Styles contributed by root defaults, the block's element tag (e.g. h2 for a level-2 Heading), the block-default layer, and the block's own style variation.

When a control has no local value, it renders its placeholder from the corresponding path in the inherited value. When a local value is present, the control renders as it does today and is marked as a local override. Reset clears the local value in a single undo step; the control then renders the placeholder again.

The inherited value is built by a pure resolver over the merged Global Styles payload already available to block-editor via settings[ globalStylesDataKey ], exposed to panels through an InheritedValueProvider / useInheritedValue surface. Resolution walks the hierarchy from deeper / more specific to broader / less specific (matching the brainstorm in #64670):

1. mergedStyles[ styleProperty ]
2. mergedStyles.elements[ elementName ][ styleProperty ]
3. mergedStyles.blocks[ blockName ][ styleProperty ]
4. mergedStyles.blocks[ blockName ].variations[ variationName ][ elementName ][ styleProperty ]
5. mergedStyles.blocks[ blockName ].variations[ variationName ][ styleProperty ]

No getComputedStyle calls, no new REST calls, no @wordpress/core-data imports in block-editor.

Tasks

Consolidated in #77894 (stacked on #77279). Items marked done are implemented in the PoC and pending review.

• Implement the inherited-value engine as a pure resolver over merged global styles settings.
• Ensure preset values (colours, font sizes, spacing presets) parse correctly via getValueFromVariable from @wordpress/global-styles-engine.
• Ensure dynamic values (theme.json "ref" pointers and relative paths) resolve via the existing helper in packages/block-editor/src/hooks/block-style-variation.js.
• Thread the inherited value through the relocated panels (typography, dimensions, colour, border, filters, background) via InheritedValueProvider.
• Migrate block controls to render placeholders from the inherited value across the archetype set listed in Scope.
• Local-override indicator + "Reset to inherited value" action.
• "Push to Global Styles" action for an individual local override.
• Source-layer breadcrumb in the inherited tooltip (bounded to the Global Styles data layers).
• Replace the PoC createPortal label adornments / DOM-selector coupling with a cleaner component API, if the direction proceeds.
• Visual treatment: placeholder uses a non-colour-only secondary signal satisfying WCAG AA.
• Preset round-trip tests for all four serialization forms.
• Design + accessibility review on the placeholder treatment. Coordinate via Styles: show a hierarchy of styles clearly (theme, user, global unspecific, global specific, local, etc) #49278.

Merge requirements

The feature PR must meet all of the following before merge:

• Lands on top of Block Supports: Relocate text and bg color controls to Typography and Background panels #77279 (rebased onto its relocated-panel layout).
• The PoC createPortal / DOM-selector affordances are replaced with a sustainable component API, or explicitly accepted by reviewers.
• Zero getComputedStyle calls introduced in feature code.
• Zero @wordpress/core-data imports introduced in block-editor.
• hasValue() ToolsPanel semantics unchanged for third-party consumers.
• WCAG AA contrast for the placeholder treatment on light editor chrome, dark site-editor chrome, and common swatch backgrounds.
• Inspector-paint p95 regression ≤ 5% on representative 50-block and 200-block fixtures.
• All four preset serialization forms round-trip correctly.

Nice to Have

• Storybook coverage for each covered control archetype in its placeholder-at-rest / focused / committed / reset states, as a lasting visual-regression surface.
• A reusable theme.json fixture committed under test/performance/ exercising the 50-block and 200-block inspector-paint benchmark (built ad-hoc during Phase 0; worth promoting).

Open Questions & Decisions required

• Visual treatment for inherited values. Several design treatments have been proposed across prior issues:

  • placeholder ghost text (this iteration's MVP choice),
  • value rendered normally with a purple label accent (Styles: show a hierarchy of styles clearly (theme, user, global unspecific, global specific, local, etc) #49278),
  • gray-ghost value rendering (Local block appearance controls should reflect values from global styles / theme.json #37752 Aug 2024 mockups from @jameskoster),
  • clickable label revealing an inheritance popover (Styles: show a hierarchy of styles clearly (theme, user, global unspecific, global specific, local, etc) #49278 original-issue sketch),
  • and the existing indeterminate-state pattern from the padding-preset control (Design tools: Better handling of unset / inherited values #43082).

  Final choice needs design sign-off on Styles: show a hierarchy of styles clearly (theme, user, global unspecific, global specific, local, etc) #49278. The placeholder-rendering MVP is chosen so alternatives B/D (label-accent + popover) remain cleanly additive for the source-attribution follow-up.

• Source-attribution depth. The tooltip already breadcrumbs the source layer within the Global Styles data. Decide how much further to take attribution within this iteration versus a follow-up — particularly sources that can't be read from that data (nested / ancestor variations, cascade) — and the final tooltip/popover shape (@annezazu's steps 3 and 4 from Styles: show a hierarchy of styles clearly (theme, user, global unspecific, global specific, local, etc) #49278).

• Non-colour secondary signal. Once the primary visual treatment is chosen, the accompanying non-colour signal (italic, dashed outline, reduced opacity, or something else) needs to satisfy WCAG AA independent of colour contrast.

• Per-archetype "inherited-equals-default" behaviour. For each archetype, decide between always render inherited value, suppress when equals default, and suppress when visually nil (e.g. padding: 0). Decisions recorded per archetype before merge.

Contributors

• @aaronrobertshaw
• @p-jackson

[aaronrobertshaw]

Prior art & implementation notes

Implementation notes and prior art for anyone picking up a PR against this issue. Continues the context from #64670 (closed, superseded by this issue) without bloating the OP.

Reusable building blocks

Three pieces already exist in packages/block-editor and @wordpress/global-styles-engine and can be called (not copied) by the implementation:

1. Merged Global Styles data in block-editor settings. The block-editor package already receives merged Global Styles through its settings payload. Consumers read it via an internal key used in packages/block-editor/src/hooks/block-style-variation.js. This means no new data pipeline is required; the editor already has the values the inspector would display.
2. ref resolution. getVariationStylesWithRefValues in packages/block-editor/src/hooks/block-style-variation.js resolves { ref: 'styles.color.background' } references against a merged payload. A pure helper modelled on it can serve as the general-purpose resolver for building the inheritedValue object.
3. Preset decode. getValueFromVariable from @wordpress/global-styles-engine is already used by every global-styles panel (color-panel.js, typography-panel.js, border-panel.js, dimensions-panel.js, background-panel.js, filters-panel.js) to map var:preset|... / var(--wp--preset--*) forms back to a displayable value. Reusing it covers all four preset serialization forms.

Dead ends

• Global Styles: Always show inherited values in the inspector if we know them #55951 ("Always show inherited values in the inspector if we know them") closed without merging its only linked PR. There is no shipped scaffolding to extend; the implementation here starts from the three building blocks above, not from residual Global Styles: Always show inherited values in the inspector if we know them #55951 code.
• Ancestor-variation and CSS-inheritance-based approaches invite layout-dependent reads (getComputedStyle) and cannot attribute values back to a specific theme.json layer without a full cascade engine. Out of scope for this issue.

Design and architecture constraints surfaced by the audit

• block-editor must remain WordPress-agnostic (no core-data imports, no direct REST calls). The resolver stays a pure function over already-available settings.
• The placeholder state needs a non-colour secondary signal; the purple token used by synced patterns and block bindings is already overloaded, so colour alone is not a sufficient differentiator.
• Element mapping (Heading → h1–h6, Button → button, Navigation/anchors → link) belongs in a single private module under unit test. Blocks without element mappings (Paragraph, Cover inner, Quote, List) are resolved at the block-default layer only.

Related issues this audit touched

• Block styles: reflect inherited global styles values in block appearance controls #64670: @ramonjd's prior implementation tracking issue (closed in favour of this one). The scope constraint ("displaying values from the merged theme.json / global styles object") and the five-level resolution hierarchy brainstormed in the thread are carried forward here.
• Local block appearance controls should reflect values from global styles / theme.json #37752: local controls reflecting theme.json values; primary user-story source for this work.
• Styles: show a hierarchy of styles clearly (theme, user, global unspecific, global specific, local, etc) #49278: styles hierarchy design + a11y review venue.
• Post Content block adds additional margin one can not remove through the UI #51242: root blockGap not inherited by Post Content inspector; canonical fixture.
• Default background color and typography from the theme are inherited on editor #68743: default theme background/typography inheritance visibility in the editor; same underlying visibility problem.
• Inconsistent padding behavior when background color is applied via Inspector vs Global Styles #77087: recently-closed report of the inspector-vs-Global-Styles behaviour split for padding; evidence that users encounter this confusion in the wild.

[eric-michel]

This issue is near and dear to my heart, because the current state of most style controls is really confusing to our users.

I do have one more (very rough, sorry) visual treatment concept for consideration. Rather than having the style selector appear on the default value, have a separate option that represents "default". Examples below:

With defaults selected

With defaults overridden

Note that these are really quickly mocked up and I'm confident someone else can produce something even more clear. The main point is that there is a totally separate selectable option that represents "default".

Why is this worth considering?

Three primary reasons:

It makes it very clear to users how to revert back to defaults. No hard-to-find RESET menu item, no blue dot that you have to hover to know what it does.

It makes it very clear to users that they are overriding the default, even when choosing the same value. The blue dot does this, and is better than the current paradigm, but isn't as immediately obvious.

It makes it easy for the editor to display that a default value is being used, even if the editor doesn't know what the default value is. If block padding is set by the theme CSS, for instance, rather than theme.json, the default option could look something like this:

or even omit the value entirely:

Yes, but...

It makes the panel taller. I suspect that will the primary argument against the concept, and I think it's a good one. I'm not sure if there's a way to produce a dedicated "default" option without making users scroll a lot more. I just know having one will be far more intuitive for users who are less technically-inclined and do not work in the editor every day.

[aaronrobertshaw]

Thanks @eric-michel for the mockups and jumping into this one 👍

The main idea here is to make the controls in the block inspector match, as closely as possible, what's actually rendered on the editor canvas. An extra selectable "Default" option runs a little counter to that goal. In its selected state the control shows nothing, whereas having the default as a placeholder or preselected in the control keeps the actual inherited value visible and aligned more to the canvas.

On the reset angle: the ToolsPanel menu already covers this. Its reset action drops the local value and the control falls back to the inherited one, which is the same pattern the Global Styles panels use when resetting to values inherited from theme.json. So selecting a "Default" option is, functionally, just resetting the control, and reset already has a home.

On override signalling: the blue dot is just one of several ideas for the override/inherit signal, and picking between them is a job best informed later on as we progress this issue and work through the source-attribution tasks in steps 2 through 4 of #49278.

For cases where no inherited value is resolvable from merged Global Styles, for instance when the theme applies styles via raw CSS or theme.json's css escape hatch, the control would simply read empty, as it does today. Functionally not very different from a "Default"-labelled empty state, and without adding another UI element per control.

You're right that the visual cost of the added option, multiplied across every control in the sidebar, would draw pushback, and rightly so. My primary concern is simpler: the proposal doesn't move the controls closer to what the user actually sees on the canvas. The closer those two are, the easier it will be to connect sidebar actions to visual results.

The plan here is to land inherited-value resolution first with minimal UI disruption, then branch off to explore different visual treatments for reset, source, and override signalling as follow-ups.

[eric-michel]

@aaronrobertshaw thanks for the reply!

I think the main point of confusion we're trying to resolve is this: Even when "Default" (or "Inherit") resolves to size Large, it is still its own option, distinct from the "Large" option, which implies its own potential behavior and characteristics.

We support a broad variety of users with an equally broad variety of technical expertise. Obviously the biggest point of confusion for them is "why does this slider show size zero when I can see that it's not?" (which this plan will resolve, thankfully). But the difference between "Default" and "Large" when they initially seem to look the same in the editor is similarly quite confusing. Ironically, making "Default" appear as "Large" as a placeholder value will make this problem worse.

A likely future scenario based on our users' experiences:

• User sees a property (like padding or margin) is currently set to Large (but is actually set to Default, which resolves to Large typically).
• User changes the property to Medium.
• User decides they do not like Medium and revert it to Large, thinking they have reset the value to its initial behavior. But in fact they have changed it from Default to Large and see no visible difference.
• Later, some other property (like a parent's Block Spacing) changes what Default resolves to for that block.
• User is confused why the block is not behaving as expected.

I recognize that my design is not a very good one, especially given the space it takes up. I'm mainly hoping that the folks working on this project will give clear distinction between Default and Large and how to select each option. Perhaps something like the blue dot will be sufficient and I am making this more complicated than it needs to be!

[aaronrobertshaw]

Thanks for the continued thoughts here @eric-michel 👍

I think there are some things worth highlighting in the scenario you outlined. I'll flesh it out a little differently:

1. Block is selected, inspector opened.
2. Size shows Large with the inherited value treatment (there's no local value set).
3. User picks Medium. The ToolsPanel menu for that control reflects that a local value is set, exposing a reset option. This happens when any local value is set, including any value equal to the inherited value.

From there, there are two different actions a user might wish to perform, "I want Large (default) back" or "I want to lock Large in".

• Revert to inherited Large: reset via the ToolsPanel menu. The inherited value is the "default". Reset is the path back to it.
• Lock Large in against upstream changes: select Large from the size control. That commits a deliberate local override that won't follow inheritance from then on.

"Large by inheritance" and "Large as an override" are two distinct and valid choices here. I don't plan at this stage to add anything like "re-selecting an inherited value" clearing the local override. It would prevent the valid use case of locking in a local override.

On the wider discoverability of the ToolsPanel reset menu: that's an editor-wide pattern used throughout the block inspector and Global Styles. This issue and work won't change that. Depending on how the experiments with different visual treatments go, we may add an affordance that makes it clearer when a control has a local override set vs an inherited placeholder.

[jameskoster]

@eric-michel have a look at the designs in #49278. I think they cover a lot of what you're talking about in a more lightweight fashion that can be applied across all control types.