Text Shadow Support in Global Styles
🔗 **Source:** [Text Shadow Support in Global Styles](https://make.wordpress.org/core/2026/07/23/text-shadow-support-in-global-styles/)
> [!note]+ Document Notes
> ---
> tags: [wordpress-7-1, global-styles, theme-json, typography, block-themes]
> author: WordPress Core contributors
> source: Make WordPress Core
> reference: https://make.wordpress.org/core/2026/07/23/text-shadow-support-in-global-styles/
> date created: {{date:YYYY-MM-DD}} {{time:HH:mm}}
> ---
> # 🏷️ Title: Text Shadow Support in Global Styles
> ## 🧭 Table of Contents
> - [📝 Summary](#-summary)
> - [📖 Main Content](#-main-content)
> - [🗒️ Notes](#️-notes)
> - [📚 References](#-references)
> - [🗣️ Paraphrase](#️-paraphrase)
> - [📰 Newsletter](#-newsletter)
> - [✅ Action Items](#-action-items)
> - [🧪 Hypotheses](#-hypotheses)
> - [📊 Methodology](#-methodology)
> - [❓ Questions](#-questions)
> - [🔮 Future Research](#-future-research)
> - [💡 Implications](#-implications)
> - [🧠 Learning Styles Assessment](#-learning-styles-assessment)
> - [📊 Accessibility Assessment](#-accessibility-assessment)
> - [🌍 DEIB Assessment](#-deib-assessment)
> - [✅ Logical Validity](#-logical-validity)
> - [🛡️ DARVO Analysis](#-darvo-analysis)
> - [🎯 Conclusion](#-conclusion)
> - [🔄 Refactor Appendix](#-refactor-appendix--text-shadow-support-in-global-styles)
> - [🧰 Template Library](#-template-library)
> ### 🔗 References
> - [Text Shadow Support in Global Styles](https://make.wordpress.org/core/2026/07/23/text-shadow-support-in-global-styles/)
> - [Typography feature request](https://github.com/WordPress/gutenberg/issues/47904)
> - [Planned text-shadow controls and presets](https://github.com/WordPress/gutenberg/pull/79584)
> ## 📝 Summary
> - WordPress 7.1 adds `textShadow` under `styles.typography` in `theme.json`.
> - Theme authors can set text shadows globally, per block, and on elements and states such as link hover.
> - The value maps directly to CSS `text-shadow`, including comma-separated multiple shadows.
> - WordPress 7.1 ships only the data-model and rendering slice. Inspector controls, Global Styles UI, presets, and block support are planned for the next release.
> - The main stakeholders are theme authors, block developers, designers, accessibility reviewers, and site owners. The main risk is unreadable or distracting text when shadows are applied without contrast and readability tests.
> - Bottom line: themes can start declaring text shadows now, but should treat them as progressive enhancement and test every state.
> ## 📖 Main Content
> - **Background:** Before 7.1, theme authors needed custom CSS because the block style system did not understand text shadows.
> - **Smallest useful slice:** Core adds the declaration path before the control design and preset system are settled.
> - **Property shape:** `styles.typography.textShadow` accepts any valid CSS `text-shadow` value. The property works at global, block, and element levels.
> - **Cascade:** Block-level values override global values like other typography styles. Element states can reset shadows, including `none` on link hover.
> - **Editor behavior:** Empty rich-text placeholders suppress the global shadow so the prompt remains readable. Actual content keeps the configured shadow in the editor and front end.
> - **Deferred work:** The next release is expected to add controls, preset storage and custom properties, and `supports.typography.textShadow` for Paragraph and Heading.
> - **Compatibility:** The change is additive. Themes that do not set the property behave as before.
> ## 🗒️ Notes
> - The feature enters through `theme.json`, not the interface. That makes it available to developers before it becomes discoverable to ordinary users.
> - The direct CSS value offers flexibility but lacks preset governance in this release.
> - Multiple shadows can create effects that are difficult to review or keep consistent across themes.
> - The placeholder reset shows that editor affordances need protection from content styles.
> - Element-state support matters because a shadow that works on default text may fail on hover, focus, or changed backgrounds.
> - The staged release isolates data storage and rendering from control design, which lowers decision coupling but creates a temporary developer-only phase.
> ## 📚 References
> - [Make WordPress Core dev note](https://make.wordpress.org/core/2026/07/23/text-shadow-support-in-global-styles/)
> - [Gutenberg issue 47904](https://github.com/WordPress/gutenberg/issues/47904)
> - [Gutenberg PR 79584](https://github.com/WordPress/gutenberg/pull/79584)
> - [MDN: text-shadow](https://developer.mozilla.org/en-US/docs/Web/CSS/text-shadow)
> ## 🗣️ Paraphrase
> - WordPress now recognizes text shadows as structured typography data instead of leaving them in custom stylesheets.
> - Themes can set the property at the same levels where they set other typography values.
> - Core deliberately ships a narrow first step: developers get configuration and rendering now, while user controls and presets wait.
> - Theme authors gain a standard path, but they remain responsible for restraint, contrast, state testing, and fallback behavior.
> ## 📰 Newsletter
> WordPress 7.1 brings `text-shadow` into `theme.json`, which means block themes can finally set shadows globally, by block, or by element without a custom stylesheet. This is the developer-first slice: no inspector control, no preset browser, and no per-block UI yet. Enjoy the new typography knob, but remember that three glowing shadows do not automatically make a heading more readable. [Read the dev note](https://make.wordpress.org/core/2026/07/23/text-shadow-support-in-global-styles/).
> ## ✅ Action Items
> #### DevRel
> - Publish restrained examples that include readability tests.
> - Explain the 7.1 scope and the next-release roadmap.
> - Run a theme-author lab covering global, block, and element states.
> - Track adoption and accessibility defects separately.
> #### OSPO
> - Record the new schema field in supported platform baselines.
> - Review copied shadow recipes for provenance and license.
> - Encourage upstream accessibility guidance and test fixtures.
> - Track theme.json schema changes across maintained products.
> #### Community
> - Maintainers: add tested examples and state coverage.
> - Contributors: report editor/front-end mismatches with minimal theme.json files.
> - Sponsors: support accessibility and visual regression work.
> - Ecosystem: share examples that favor legibility over decoration.
> #### WordPress
> - Core: document schema, cascade, validation, and release boundaries.
> - Core Performance: measure CSS output and style-engine cost for multiple shadows.
> - Core AI: stop generated designs from adding unreadable decorative shadows by default.
> - Core Program Team: track the dependency chain from schema to presets, controls, docs, and accessibility review.
> - Mobile: confirm rendering and editing parity or document limits.
> - Playground: host a theme.json typography lab.
> - Community: include the feature in block-theme developer sessions.
> - Training: teach progressive enhancement and state testing.
> - Marketing: present it as a developer capability in 7.1, not a complete user control.
> - Support: document how to remove or override an unreadable shadow.
> - Design: define sensible control ranges and preset previews.
> - Documentation: add schema examples and the list of deferred features.
> - Photos: no direct action.
> - TV: caption a short Global Styles demo.
> - Polyglots: test controls and labels once the UI arrives.
> - Accessibility: test contrast, blur, cognitive load, hover, focus, zoom, and forced-colors behavior.
> - Meta: avoid decorative shadows on high-density administrative text.
> - CLI: expose schema validation and theme.json linting examples.
> - Hosting: include 7.1 theme.json validation in staging checks.
> - Tide: consider checks for extreme or unreadable shadow values only if false positives stay low.
> - Openverse: test captions and attribution text under inherited global shadows.
> - Themes: review global inheritance and reset sensitive components.
> - Plugins: honor theme.json output without duplicating conflicting CSS.
> #### The WPCC
> - Fund a small accessible typography recipe library.
> - Support shared theme.json test fixtures across theme projects.
> ### FAIR
> - Keep text-shadow settings in portable theme metadata.
> - Document schema versions and fallback behavior.
> - Publish accessibility expectations for distributed theme packages.
> ## 🧪 Hypotheses
> - Data-model
WordPress 7.1 introduces the ability to define a `text-shadow` value in Global Styles through `theme.json`. Themes can now set a text shadow globally, on specific blocks, and on elements such as links, without a plugin or custom stylesheet.
This is the first step of the text shadow feature. It covers `theme.json` styling only. A user interface, presets, and per-block-instance controls arrive in the next release. See the “What is not included yet” section below.
#### Background
The CSS `text-shadow` property has been a frequently requested typography feature (see [#47904](https://github.com/WordPress/gutenberg/issues/47904)). Until now, applying a text shadow through the block system was not possible. Theme authors had to add their own CSS to style text shadows, which kept the value outside of `theme.json` and Global Styles.
Fully implementing text shadow raises questions that still need discussion, such as the right control for editing shadows and whether shadows should be stored as presets. To make progress without waiting on those decisions, this release adds the smallest useful piece: the ability to declare a `text-shadow` value directly in `theme.json`.
#### What changed
A `textShadow` property is now recognized under `styles.typography` in `theme.json`. The value maps directly to the CSS `text-shadow` property, so any valid `text-shadow` value works, including multiple comma-separated shadows.
The property is supported in the same places as other typography styles:
* Global typography (`styles.typography`)
* Per-block styles (`styles.blocks.<block>.typography`)
* Element styles, including states such as `:hover` (`styles.elements.<element>`)
There is no block inspector control and no Global Styles interface for this in this release. The value is set in `theme.json` only.
#### How to use it
Set `textShadow` under `styles.typography` to apply a shadow to all text. The example below applies a global shadow, overrides it for the Paragraph block, and removes the shadow from links on hover.
```
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"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"
}
}
}
}
}
}
```
Block-level values override the global value, following the same cascade as other typography styles.
#### Editor behavior
When a global text shadow is set, the shadow is removed from the empty rich text placeholder (for example the “Type / to choose a block” prompt). Without this reset, the placeholder text can become hard to read. The reset applies to the placeholder only. Actual content still renders with the configured shadow in both the editor and on the front end.
#### What is not included yet
This release covers `theme.json` styling only. The following are planned for the next release in [#79584](https://github.com/WordPress/gutenberg/pull/79584):
* A text shadow control in the block inspector, so a shadow can be set on an individual block instance.
* A Global Styles interface for browsing, creating, and editing text shadow presets.
* Text shadow presets in `theme.json` (`settings.typography.textShadow`, `textShadowPresets`, and `defaultTextShadowPresets`), each output as a `var(--wp--preset--text-shadow--{slug})` custom property.
* A new `supports.typography.textShadow` block support, enabled first on the Paragraph and Heading blocks.
Until then, text shadow can be configured through `theme.json` styles as shown above.
These are additive changes. No existing blocks or themes are affected, and no action is required. Themes that do not set `textShadow` behave exactly as before.
*Props to* [@wildworks](https://profiles.wordpress.org/wildworks/) *for reviewing this post.*, Text Shadow Support in Global Styles, WordPress Core contributors, 01ky7rgwsw4f5qw5q8bre8h2va.