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).
When & Why to Use This Skill
This Claude skill streamlines the development of modern WordPress block themes by automating the creation and management of theme.json files, HTML templates, and PHP patterns. It ensures adherence to WordPress 6.9+ standards, simplifies style hierarchy debugging, and facilitates the implementation of global settings and style variations for Full Site Editing (FSE).
Use Cases
- Configuring global styles, color palettes, and typography presets within the theme.json framework to ensure site-wide consistency.
- Building and organizing block-based templates and template parts (e.g., headers, footers) for custom page layouts.
- Developing reusable block patterns and style variations to provide flexible design options within the WordPress Site Editor.
- Troubleshooting and resolving style conflicts between theme.json settings, user customizations, and core CSS defaults.
- Automating the structural setup of new WordPress block themes, including required file hierarchies and JSON schema validation.
| name | wp-block-themes |
|---|---|
| description | "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)." |
| compatibility | "Targets WordPress 6.9+ (PHP 8.0+). Filesystem-based agent with bash + node." |
WP Block Themes
When to use
Use this skill for block theme work such as:
- Editing
theme.json(presets, settings, styles, per-block styles) - Adding or changing templates (
templates/*.html) and template parts (parts/*.html) - Adding patterns (
patterns/*.php) and controlling inserter visibility - Adding style variations (
styles/*.json) - Debugging "styles not applying" / "editor doesn't reflect theme.json"
Inputs required
- Repo root and which theme is targeted
- Target WordPress version range (theme.json version varies by core version)
- Where the issue manifests: Site Editor, post editor, frontend, or all
Procedure
1) Verify block theme structure
Required structure:
theme-name/
├── style.css # Theme header (required)
├── theme.json # Global settings and styles (required)
├── templates/ # Full page templates
│ ├── index.html # Fallback template (required)
│ ├── single.html
│ ├── archive.html
│ └── ...
├── parts/ # Template parts
│ ├── header.html
│ ├── footer.html
│ └── ...
├── patterns/ # Block patterns (optional)
│ └── *.php
└── styles/ # Style variations (optional)
└── *.json
2) theme.json structure
Settings (what the UI allows):
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
"color": {
"palette": [
{ "slug": "primary", "color": "#0073aa", "name": "Primary" }
]
},
"typography": {
"fontSizes": [
{ "slug": "small", "size": "14px", "name": "Small" }
]
},
"layout": {
"contentSize": "800px",
"wideSize": "1200px"
}
}
}
Styles (how it looks by default):
{
"styles": {
"color": {
"background": "var(--wp--preset--color--base)",
"text": "var(--wp--preset--color--contrast)"
},
"elements": {
"link": {
"color": { "text": "var(--wp--preset--color--primary)" }
}
},
"blocks": {
"core/button": {
"color": {
"background": "var(--wp--preset--color--primary)"
}
}
}
}
}
3) Templates and template parts
Templates (templates/*.html):
<!-- wp:template-part {"slug":"header"} /-->
<!-- wp:group {"tagName":"main"} -->
<main class="wp-block-group">
<!-- wp:post-title /-->
<!-- wp:post-content /-->
</main>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer"} /-->
Template parts (parts/*.html):
- Must NOT be nested in subdirectories
- Must have matching
slugin template-part block
4) Patterns
Create patterns in patterns/*.php:
<?php
/**
* Title: Hero Section
* Slug: theme-name/hero
* Categories: featured
* Keywords: hero, banner
*/
?>
<!-- wp:cover {"url":"..."} -->
...
<!-- /wp:cover -->
5) Style variations
Create variations in styles/*.json:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"title": "Dark Mode",
"settings": {},
"styles": {
"color": {
"background": "#1a1a1a",
"text": "#ffffff"
}
}
}
6) Style hierarchy (debugging)
Styles apply in this order (later overrides earlier):
- Core defaults
- theme.json (parent theme)
- theme.json (child theme)
- User customizations (stored in DB)
If your theme.json changes don't appear:
- Check if user customizations override them
- Clear any caches
- Validate JSON syntax
Verification
- Site Editor reflects changes (Styles UI, templates, patterns)
- Frontend renders with expected styles
- If styles aren't changing, confirm user customizations don't override
Failure modes / debugging
Common issues:
- Wrong theme root: Editing inactive theme
- User overrides: Customizations in DB override theme.json
- Invalid JSON: Typos prevent application
- Wrong folder: Templates/parts in wrong location or nested
Debug commands:
# Validate theme.json
cat theme.json | python3 -m json.tool
# Check template files
ls -la templates/ parts/
# Verify theme is active
wp theme list --status=active
Escalation
Consult canonical docs: