Global Styles: Add textShadow style support

[t-hamano]

• Part of Typography: Add "Text shadow" support #47904
• Split tasks from text-shadow option support in Typography Panel #71419

What?

This PR allows text-shadow CSS styles to be defined in theme.json.

Why? How?

Looking at #47904, the Text Shadow support seems to be a feature requested by many users.

However, to fully implement this, we need to discuss the following at least:

• What is an appropriate UI for controlling text shadows?
• Should we be able to define text shadows as presets?

This PR is the first small feature improvement, allowing us to simply define text-shadow under the styles.typography.

Testing Instructions

For example, use a theme.json like the one below and make sure it works correctly in all scenarios:

{
	"$schema": "../../schemas/json/theme.json",
	"version": 3,
	"settings": {
		"appearanceTools": true,
		"layout": {
			"contentSize": "840px",
			"wideSize": "1100px"
		}
	},
	"styles": {
		"typography": {
			"textShadow": "1px 1px 2px red, 0 0 1em blue, 0 0 0.2em blue;"
		},
		"blocks": {
			"core/paragraph": {
				"typography": {
					"textShadow": "1px 1px 2px red, 0 0 1em red, 0 0 0.2em red;"
				}
			}
		},
		"elements": {
			"link": {
				":hover": {
					"typography": {
						"textShadow": "none"
					}
				}
			}
		}
	}
}

Screenshots or screencast

[t-hamano]

I wasn't sure whether to add this, but if we don't reset the shadow, the placeholder is very hard to see.

[github-actions]

Size Change: +51 B (0%)

Total Size: 7.51 MB

📦 View Changed

Filename	Size	Change
build/scripts/style-engine/index.min.js	2.46 kB	+18 B (+0.74%)
build/styles/block-editor/content-rtl.css	5.56 kB	+8 B (+0.14%)
build/styles/block-editor/content-rtl.min.css	4.13 kB	+9 B (+0.22%)
build/styles/block-editor/content.css	5.56 kB	+8 B (+0.14%)
build/styles/block-editor/content.min.css	4.13 kB	+8 B (+0.19%)

_{compressed-size-action}

[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: USERSATOSHI <[email protected]>
Co-authored-by: t-hamano <[email protected]>
Co-authored-by: aaronrobertshaw <[email protected]>
Co-authored-by: ramonjd <[email protected]>
Co-authored-by: noruzzamans <[email protected]>

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

[noruzzamans]

I tested this PR locally and the textShadow global style seems to work as described.

Test setup:

• Local WP install with the Gutenberg plugin checked out to the text-shadow-style-support branch.
• Twenty Twenty-Five theme active.
• theme.json replaced with the example from the testing instructions.

Results:

– In the post editor, the heading block correctly receives the global styles.typography.textShadow value.

– The paragraph block uses the block-level override from
styles.blocks["core/paragraph"].typography.textShadow, so its shadow is different from the heading’s shadow.

– Links inside the paragraph show the shadow normally, and on hover the shadow is removed as expected thanks to
elements.link[:hover].typography.textShadow = "none". (See attached screenshot of the hovered link.)

– When I insert a new Paragraph block and leave it empty, the placeholder text (“Type / to choose a block”) does not inherit
the global shadow and stays readable, so the text-shadow: none; reset on the rich-text placeholder looks correct.

– On the front end, the same textShadow behavior matches what I see in the editor (headings, paragraphs and links all
reflect the configuration from theme.json).

Overall, from a theme author’s perspective, the behavior looks consistent and the feature works well in my tests.
Screenshots from the editor and front end are attached for reference.

[aaronrobertshaw]

Thanks for all the work on this @t-hamano 👍

This might just be me but splitting up the changes for the block support here, makes it much harder to actually confirm that all the places required have been updated.

Reviewing the changes as they are currently though there are a couple of minor issues:

• Need to update: docs/reference-guides/theme-json-reference/styles-versions.md
• Text shadow should be added to the VALID_SETTINGS in the theme.json class too
• Needs to update docs/reference-guides/theme-json-reference/theme-json-living.md for settings after update above
• Once setting for text shadow has been added we also need a default setting value in lib/theme.json
• Also, it looks like the style engine's PHP typography config hasn't been updated here or in #71419

[t-hamano]

@aaronrobertshaw Thanks for the review!

However, to fully implement this, we need to discuss the following at least:

• What is an appropriate UI for controlling text shadows?
• Should we be able to define text shadows as presets?

This is the main reason why I split the tasks.

Also, since this PR is solely focused on style, I purposely left out the settings.

That said, if addressing everything at once is easier, I'm happy to prioritize #71419 👍

[t-hamano]

@aaronrobertshaw Thanks for the feedback!

Since this PR intentionally covers only the theme.json styles side of things, could you update the parent tracking issue with the full list of follow-ups? For example, Block Supports plumbing, UI controls, and docs.

Yes, here are all the follow-up tasks I could think of: #47904 (comment)

1. TypeScript Types: packages/style-engine/src/types.ts:61-71 — the typography branch of the Style type is missing textShadow?: CSSProperties[ 'textShadow' ];. We should add this so external typed consumers don't hit errors.
2. JS Test Coverage: Could we add a textShadow assertion alongside the existing textDecoration/textTransform cases?
3. Placeholder Reset: I noticed that while the rich-text reset is there, the placeholder text for a paragraph block still gets the shadow until it is selected. You can easily see this when creating a new post.

I have fixed all of these.

[ramonjd]

This is testing well for me. Thanks for linking to the follow ups.

Also, would we need to update docs/reference-guides/theme-json-reference/styles-versions.md ?

[ramonjd]

That said, if addressing everything at once is easier, I'm happy to prioritize #71419 👍

I'm guessing the UI will be the slowest/trickiest bit to get right. I'm happy for this to get in with the block level support/controls as a follow up. Though the preference would be to ship the entire feature (global styles + block supports) if it gets into 7.1. Is there enough time for that? What do folks think?

[t-hamano]

Also, would we need to update docs/reference-guides/theme-json-reference/styles-versions.md ?

Nice catch, updated in 858347e.

Additionally, I fixed an issue with the style engine lacking support in b33baa3.

[t-hamano]

Though the preference would be to ship the entire feature (global styles + block supports) if it gets into 7.1. Is there enough time for that? What do folks think?

With three weeks left until Beta1, but implementation should not take long as there is precedent code. Specifically, the shadow preset UI should be reusable almost as-is for the text shadow preset UI.

The UI for block instances has also been sufficiently discussed here. #47904 (comment)

If it takes time, it will likely be about deciding on the default presets, which tend to be the most divisive. However, even if everything doesn't make it in time for 7.1, I believe it's still worthwhile to ship the style support alone.

[ramonjd]

[t-hamano]

@aaronrobertshaw, do you have any concerns before merging this PR?

[aaronrobertshaw]

I've given this another smoke test in particular around the placeholder reset and my recent review items.

LGTM 🚢

[t-hamano]

Thank you both! I'd like to merge this PR and move on to the remaining tasks.

P.S. This PR might be worth mentioning as part of the Misc Dev note.

[t-hamano]

A follow-up PR addressing the remaining tasks: WordPress/wordpress-develop#12011