Wp Block Themes

1---
2name: wp-block-themes
3description: "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)."
4compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
5---
6 
7# WP Block Themes
8 
9## When to use
10 
11Use this skill for block theme work such as:
12 
13- editing `theme.json` (presets, settings, styles, per-block styles)
14- adding or changing templates (`templates/*.html`) and template parts (`parts/*.html`)
15- adding patterns (`patterns/*.php`) and controlling what appears in the inserter
16- adding style variations (`styles/*.json`)
17- debugging “styles not applying” / “editor doesn’t reflect theme.json”
18 
19## Inputs required
20 
21- Repo root and which theme is targeted (theme directory if multiple exist).
22- Target WordPress version range (theme.json version and features vary by core version).
23- Where the issue manifests: Site Editor, post editor, frontend, or all.
24 
25## Procedure
26 
27### 0) Triage and locate block theme roots
28 
291. Run triage:
30   - `node skills/wp-project-triage/scripts/detect_wp_project.mjs`
312. Detect theme roots + key folders:
32   - `node skills/wp-block-themes/scripts/detect_block_themes.mjs`
33 
34If multiple themes exist, pick one and scope all changes to that theme root.
35 
36### 1) Create a new block theme (if needed)
37 
38If you are creating a new block theme from scratch (or converting a classic theme):
39 
40- Prefer starting from a known-good scaffold (or exporting from a WP environment) rather than guessing file layout.
41- Be explicit about the minimum supported WordPress version because `theme.json` schema versions differ.
42 
43Read:
44- `references/creating-new-block-theme.md`
45 
46After creating the theme root, re-run `detect_block_themes` and continue below.
47 
48### 2) Confirm theme type and override expectations
49 
50- Block theme indicators:
51  - `theme.json` present
52  - `templates/` and/or `parts/` present
53- Remember the style hierarchy:
54  - core defaults → theme.json → child theme → user customizations
55  - user customizations can make theme.json edits appear “ignored”
56 
57Read:
58- `references/debugging.md` (style hierarchy + fastest checks)
59 
60### 3) Make `theme.json` changes safely
61 
62Decide whether you are changing:
63 
64- **settings** (what the UI allows): presets, typography scale, colors, layout, spacing
65- **styles** (how it looks by default): CSS-like rules for elements/blocks
66 
67Read:
68- `references/theme-json.md`
69 
70### 4) Templates and template parts
71 
72- Templates live under `templates/` and are HTML.
73- Template parts live under `parts/` and must not be nested in subdirectories.
74 
75Read:
76- `references/templates-and-parts.md`
77 
78### 5) Patterns
79 
80Prefer filesystem patterns under `patterns/` when you want theme-owned patterns.
81 
82Read:
83- `references/patterns.md`
84 
85### 6) Style variations
86 
87Style variations are JSON files under `styles/`. Note: once a user picks a style variation, that selection is stored in the DB, so changing the file may not “update what the user sees” automatically.
88 
89Read:
90- `references/style-variations.md`
91 
92## Verification
93 
94- Site Editor reflects changes where expected (Styles UI, templates, patterns).
95- Frontend renders with expected styles.
96- If styles aren’t changing, confirm whether user customizations override theme defaults.
97- Run the repo’s build/lint scripts if assets are involved (fonts, custom JS/CSS build).
98 
99## Failure modes / debugging
100 
101Start with:
102 
103- `references/debugging.md`
104 
105Common issues:
106 
107- wrong theme root (editing an inactive theme)
108- user customizations override your defaults
109- invalid `theme.json` shape/typos prevent application
110- templates/parts in wrong folders (or nested parts)
111 
112## Escalation
113 
114If upstream behavior is unclear, consult canonical docs:
115 
116- Theme Handbook and Block Editor Handbook for `theme.json`, templates, patterns, and style variations.
117