theme.json schema: fix block pseudo-classes and custom states

[ramonjd]

What?

Closes #81057. Supersedes #81073.

Makes the schema accept the block-level states WordPress already supports: :hover, :focus, :focus-visible, :active on core/button and core/navigation-link, -current on core/navigation-link, and elements on core/button.

Why?

The rules appeared to be already in the schema but never applied.

Every core block is listed under properties and was also matched by a generic patternProperties fallback; JSON Schema applies both, and the fallback's propertyNames rejected the extra keys. An allOf member can only narrow a key set, never widen it.

How?

• Fallback moves from patternProperties to additionalProperties, which only applies to blocks not listed under properties. A propertyNames pattern still rejects malformed block names.
• -current no longer pulls in stylesPropertiesComplete, so a nested :hover validates.
• core/navigation-link and core/button declare their own key sets, at block and style-variation level.

Testing Instructions

npm run test:unit -- test/integration/theme-schema.test.js

New fixture test/integration/fixtures/theme-json/block-states/theme.json is rejected on trunk and accepted here. Six expected-invalid fixtures keep asserting these states are refused on blocks that don't support them.

To check in an editor, drop this in a theme.json and open it your editor. Example assumes you're testing locally in this repo. Swap the $schema for https://schemas.wp.org/trunk/theme.json to compare.

All the following are valid:

{
	"$schema": "../../schemas/json/theme.json",
	"version": 3,
	"styles": {
		"elements": {
			"link": {
				":hover": { "color": { "text": "#005177" } },
				":visited": { "color": { "text": "#663399" } }
			},
			"button": {
				":hover": { "color": { "background": "#005177" } }
			}
		},
		"blocks": {
			"core/button": {
				"color": { "background": "#0073aa" },
				":hover": { "color": { "background": "#005177" } },
				":focus-visible": { "outline": { "width": "2px" } },
				"elements": { "link": { "color": { "text": "currentColor" } } },
				"@mobile": { ":hover": { "color": { "background": "red" } } },
				"variations": {
					"outline": {
						":hover": { "color": { "text": "red" } },
						"@mobile": { ":hover": { "color": { "text": "red" } } },
						"elements": { "link": { "color": { "text": "red" } } },
						"blocks": { "core/paragraph": { "color": { "text": "red" } } }
					}
				}
			},
			"core/navigation-link": {
				":hover": { "color": { "text": "#005177" } },
				"-current": {
					"color": { "text": "#0073aa" },
					":hover": { "color": { "text": "#005177" } }
				},
				"@tablet": { ":hover": { "color": { "text": "red" } } },
				"variations": {
					"outline": {
						":hover": { "color": { "text": "red" } },
						"@mobile": { ":hover": { "color": { "text": "red" } } }
					}
				}
			},
			"core/group": {
				"elements": {
					"link": { ":hover": { "color": { "text": "#005177" } } }
				}
			}
		},
		"variations": {
			"custom-variation": {
				"blocks": {
					"core/button": { "@mobile": { ":hover": { "color": { "text": "red" } } } },
					"core/navigation-link": { "@mobile": { ":hover": { "color": { "text": "red" } } } }
				}
			}
		}
	}
}

These examples should contain invalid entries:

{
	"$schema": "../../schemas/json/theme.json",
	"version": 3,
	"styles": {
		"blocks": {
			"core/paragraph": {
				":hover": { "color": { "text": "red" } },
					"@mobile": { ":hover": { "color": { "text": "red" } } },
					"variations": { "outline": { ":hover": { "color": { "text": "red" } } } }
			},
			"core/button": {
				":visited": { "color": { "text": "red" } },
				"@mobile": { ":visited": { "color": { "text": "red" } } },
				"variations": { "outline": { "colour": {} } }
			},
			"core/navigation": {
				"-current": { "color": { "text": "red" } }
			},
			"core/navigation-link": {
				"-active": { "color": { "text": "red" } },
				"variations": { "outline": { "-current": { "color": { "text": "red" } } } },
				"@mobile": { "-current": { "color": { "text": "red" } } },
				"-current": { "@mobile": { "color": { "text": "red" } } }
			}
		}
	}
}

Expected: no warnings on core/button or core/navigation-link, and :hover under core/paragraph still flagged, since that block has no pseudo-class support.

[github-actions]

Flaky tests detected in 07c8c92.
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/30984306212
📝 Reported issues:

• [Flaky Test] submenu converts to link automatically #58981 in /test/e2e/specs/editor/blocks/navigation.spec.js

[ramonjd]

Note for a follow up:

blocks.["some/block"]["@mobile"].elements is rejected by the schema although sanitize adds it (:1320) and get_block_nodes() emits nodes for it (:3726-3731).

That's related to the responsive-states feature, not pseudo/-current, and it touches all blocks. Should we handle that separately?

[t-hamano]

I don't have time to review this PR yet, but let's backport it to 7.1 as some developers might refer to the schema in the wp/7.1 branch.

[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: tellthemachines <isabel_brison@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>
Co-authored-by: yashjawale <yashjawale@git.wordpress.org>
Co-authored-by: mrleemon <leemon@git.wordpress.org>

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

[ramonjd]

That's related to the responsive-states feature, not pseudo/-current, and it touches all blocks. Should we handle that separately?

PR here:

• theme.json schema: responsive states belong to blocks #81253

[Copilot]

Pull request overview

Fixes theme.json validation for supported block pseudo-classes and navigation-link custom states while preserving strict validation elsewhere.

Changes:

• Adds block-specific schemas for Button and Navigation Link states.
• Reworks fallback validation to avoid overriding explicit block schemas.
• Adds valid and invalid schema fixtures covering supported and rejected states.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
schemas/json/theme.json	Defines supported block states and correct fallback validation.
test/integration/fixtures/theme-json/block-states/theme.json	Covers valid state combinations.
test/integration/fixtures/schemas/stylesVariationBlockPropertiesComplete.json	Retains invalid-property coverage for variations.
test/integration/fixtures/schemas/stylesVariationBlockPropertiesComplete_pseudo.json	Rejects pseudo-classes on unsupported variation blocks.
test/integration/fixtures/schemas/stylesPropertiesAndElementsComplete.json	Retains invalid block-property coverage.
test/integration/fixtures/schemas/stylesPropertiesAndElementsComplete_thirdParty.json	Rejects unsupported third-party block pseudo-classes.
test/integration/fixtures/schemas/stylesPropertiesAndElementsComplete_pseudo.json	Rejects pseudo-classes on unsupported core blocks.
test/integration/fixtures/schemas/stylesBlockVariationsWithPseudoProperties.json	Rejects custom states inside block variations.
test/integration/fixtures/schemas/stylesBlocksResponsiveSelectorsWithPseudoProperties.json	Rejects unsupported responsive pseudo-classes.
test/integration/fixtures/schemas/stylesBlocksResponsiveSelectorsProperties.json	Rejects responsive pseudo-classes on unsupported blocks.
test/integration/fixtures/schemas/stylesBlocksPropertiesComplete.json	Rejects malformed block names.
test/integration/fixtures/schemas/stylesBlocksPropertiesComplete_navigationLink.json	Rejects unknown navigation-link states.
test/integration/fixtures/schemas/stylesBlocksCustomStatesProperties.json	Rejects invalid properties within custom states.

[tellthemachines]

The changes themselves look sensible, I just don't understand the tests 😅

One thought, not for now though: at some point we'll want to allow third party blocks to add support for pseudo styles; is there a semantic way to reflect that in the schema? Like: this feature exists for any blocks that declare support for it?

[tellthemachines]

curious why this change?

[ramonjd]

After this PR core/button no longer reaches the stylesPropertiesAndElementsComplete definition.

On trunk core/button was validated twice: by its own entry under properties, and again by the generic patternProperties fallback, which is stylesPropertiesAndElementsComplete.

That double validation is the bug being fixed here.

I let Claude have at it again, and it identified a gap though thanks to your question:

stylesBlocksResponsiveSelectorsWithPseudoProperties.json (rejects :visited under @mobile) and stylesVariationPropertiesComplete.json (rejects a bad key inside a button variation), but nothing now asserts that an unknown key sitting directly on core/button is rejected, which is what this fixture used to do.

I can add stylesBlocksPropertiesComplete_button.json to cover it:

{
	"$schema": "../../../../schemas/json/theme.json",
	"version": 3,
	"styles": {
		"blocks": {
			"core/button": {
				"invalidAdditionalProperty": true
			}
		}
	}
}

[ramonjd]

I can add stylesBlocksPropertiesComplete_button.json to cover it:

Done in 58aa81a

[tellthemachines]

I assume this and the below are the invalid test cases? Whereabouts are we asserting their invalidity? Not sure I understand how these tests work 😅

[ramonjd]

Fair question. I had no idea that these tests even existed before yesterday 😄

Invalidity assertions are made over in https://github.com/WordPress/gutenberg/blob/trunk/test/integration/theme-schema.test.js#L17

So creating a file in fixtures/schemas/ is the "assertion" that it's invalid.

[tellthemachines]

Again, where is this being tested? Is there a doc somewhere that explains how these tests work?

[ramonjd]

test/integration/README.md isn't much help - it has one line "Validates all theme.json files in the repo against the JSON schema", which is, by all standards, unhelpful.

I could probably spin up another PR to expand that.

[ramonjd]

Done in

• Docs: explain how the theme.json schema fixtures work #81263

[tellthemachines]

LGTM now I understand the tests better 😂
the important thing is schema accuracy i guess

[github-actions]

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