wp-block-themes

Use when developing WordPress block themes: theme.json (global settings/styles), templates and template parts, patterns, style variations, and Site Editor troubleshooting (style hierarchy, overrides, caching).

1,627stars225forksUpdated 6/4/2026

Documentation #php #theme-development #documentation #wordpress #block-themes #nodejs

Security Assessment

Safe(100/100)

Security Score100/100

About wp-block-themes

The `wp-block-themes` skill is designed to streamline and enhance the development of WordPress block themes. It provides a structured approach for managing the various components of block themes, including global settings in `theme.json`, templates, template parts, patterns, and style variations. By guiding developers through best practices for theme creation, modification, and debugging, this skill helps solve common challenges such as theme styling conflicts, ineffective updates due to caching or user customizations, and proper theme hierarchy management. It ensures that changes made to the theme are correctly reflected in both the Site Editor and the frontend environment, reducing the likelihood of errors and inconsistencies.

This skill offers capabilities for editing `theme.json` files to configure presets, typography, colors, layout, and per-block styles, as well as for adding or updating templates and template parts. It includes procedures for introducing new patterns and style variations, along with guidance on how to handle their visibility and persistence. Additionally, the skill covers troubleshooting techniques to identify and resolve common failure modes, such as incorrect theme roots, invalid JSON structures, and overrides caused by user customizations. It provides reference materials for creating new block themes, understanding style hierarchy, and debugging issues effectively, ensuring developers can follow a consistent and reliable workflow.

The skill is particularly useful for WordPress developers working on modern block themes who need to manage complex theme structures and maintain compatibility across different WordPress versions (6.9+). It is also beneficial for teams managing multiple themes within a project, as it clarifies theme detection, scoping, and change verification. Typical use cases include creating new block themes, updating existing themes, customizing templates, applying style variations, and troubleshooting style application issues in the Site Editor or frontend. By using this skill, developers can confidently implement design changes while minimizing conflicts with user customizations or core defaults.

FAQ

Which WordPress versions are compatible with this skill?

This skill targets WordPress 6.9 and higher and requires PHP 7.2.24 or above. Compatibility may vary depending on the `theme.json` schema version and available features in the targeted WordPress core version.

Can I use this skill to create a block theme from scratch?

Yes, the skill provides guidance for creating new block themes, including using known-good scaffolds or exporting from a WordPress environment, and emphasizes setting a minimum supported WordPress version.

What should I do if my theme changes are not reflecting in the Site Editor?

Check for user customizations that may override theme defaults, verify that the `theme.json` structure is valid, ensure templates and parts are in the correct folders, and consult the debugging references provided.

Are style variations automatically updated for users after changing the JSON file?

No. Once a user selects a style variation, that choice is stored in the database. Changing the file does not automatically update the user's current selection.