EP07. "wp-theme-development 主题开发审查"

• Block theme 明明配好了 theme.json 的色板和间距预设，模板文件里却还是 style="color: #333; padding: 2rem;" 硬编码——等于白配了一套设计系统，编辑在后台改主题色完全没用
• wp-theme-development 是 jorgerosal/wordpress-skills 里专盯 WordPress 6.6+ 主题的技能，主力审 block theme（Full Site Editing），也覆盖 classic theme 的迁移建议
• 核心转变：block theme 用 HTML 模板 + block 标记 + theme.json 管理全局设置/样式，取代了过去 PHP 模板 + add_theme_support() 的写法，theme.json v3 是设计配置的唯一真相来源
• 会自动判断主题类型（block / classic / hybrid / child / WordPress.org 提交）并按类型调整审查标准，前置知识同前几篇：先看过「Claude Code 新手上手」「Skills 介绍」和 EP01 了解这套 skill 包怎么调用

重点内容

这个 Skill 是做什么的

系统审查 theme.json 结构、block 模板层级（templates/ 下的 HTML 文件）、模板部件（parts/）、全局样式、样式变体（style variations）、主题里的 block patterns、子主题兼容性、classic-to-block 迁移机会。审查同时覆盖 PHP（functions.php、classic 模板）、HTML block 模板文件（templates/、parts/）、JSON 文件（theme.json、样式变体）、PHP pattern 文件（patterns/）。

适合用在：

• Block theme 代码审查（theme.json、HTML 模板、模板部件）
• theme.json v3 schema 校验与结构检查
• 模板层级审计（block theme 的 .html 文件，classic theme 的 .php 文件）
• 模板部件审查（parts/header.html、parts/footer.html、parts/sidebar.html）
• 全局样式分析（色板、字体排印、间距、布局设置）
• 样式变体校验（styles/ 目录下的多份 theme.json）
• 子主题兼容性检查（block 或 classic 子主题）
• Classic-to-block 主题迁移评估
• WordPress.org 主题提交就绪度检查（Theme Check 合规）
• Block theme 里硬编码样式的检测

不适合用在：

• Block editor 组件审查（React/JSX block，交给 wp-block-development）
• 插件架构审查（交给 wp-plugin-development）
• 纯安全审查（交给 wp-security-review）
• 纯性能审查（交给 wp-performance-review）
• WooCommerce 主题集成
• 纯视觉设计评估（这是代码审查，不是 UI/UX 评审）

触发方式

先判断主题类型，审查标准会跟着变

实操示例：block 模板硬编码 vs 用 theme.json 预设

<!-- ❌ CRITICAL：硬编码内联样式，直接架空了 theme.json 的存在意义 -->
<!-- wp:template-part {"slug":"header"} /-->

<main style="max-width: 1200px; margin: 0 auto; padding: 2rem; color: #333;">
	<h1 style="font-size: 32px; color: #0073aa;">Post Title</h1>
	<div style="font-size: 16px; line-height: 1.6;">
		<!-- wp:post-content /-->
	</div>
</main>

<!-- wp:template-part {"slug":"footer"} /-->

<!-- ✅ GOOD：用 block 属性和 theme.json 预设，改主题色/间距全站联动 -->
<!-- wp:template-part {"slug":"header","area":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
	<!-- wp:post-title {"level":1} /-->

	<!-- wp:group {"layout":{"type":"flex","flexWrap":"nowrap"}} -->
	<div class="wp-block-group">
		<!-- wp:post-author {"showAvatar":true} /-->
		<!-- wp:post-date /-->
	</div>
	<!-- /wp:group -->

	<!-- wp:post-content {"layout":{"type":"constrained"}} /-->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","area":"footer"} /-->

实操示例：useRootPaddingAwareAlignments 这个最容易配错的开关

// ❌ BAD：设了根 padding，却没开 useRootPaddingAwareAlignments
// —— 结果是全宽 block 左右两边会莫名多出一截留白
{
	"version": 3,
	"styles": {
		"spacing": {
			"padding": { "left": "2rem", "right": "2rem" }
		}
	}
}

// ❌ BAD：开了 useRootPaddingAwareAlignments，但 padding 写成 CSS 简写字符串
// —— 这样不生效，必须用对象写法
{
	"version": 3,
	"settings": { "useRootPaddingAwareAlignments": true },
	"styles": { "spacing": { "padding": "2rem" } }
}

// ✅ GOOD：useRootPaddingAwareAlignments 配上对象写法的 padding
{
	"version": 3,
	"settings": { "useRootPaddingAwareAlignments": true },
	"styles": {
		"spacing": {
			"padding": {
				"top": "var(--wp--preset--spacing--50)",
				"right": "var(--wp--preset--spacing--50)",
				"bottom": "var(--wp--preset--spacing--50)",
				"left": "var(--wp--preset--spacing--50)"
			}
		}
	}
}

怎么安装

这个 skill 是 wordpress-skills 这个开源仓库（jorgerosal/wordpress-skills）打包的 18 个技能之一，安装一次，18 个技能一起到位，不用逐个装：

Claude Code：

装完重启 Claude Code，进到一个 WordPress 项目里跑 /wordpress-skills:wp-theme-review 验证有没有装成功（用 marketplace/submodule 方式装的话，指令前面会带插件命名空间 wordpress-skills:；用「只装这一个 skill」的方式则不带命名空间，直接 /wp-theme-review）。

Claude Desktop / claude.ai： 走 Settings → Capabilities → Skills，上传技能文件夹（把 claude-skills/wp-theme-development 这个文件夹打包上传，里面要包含 SKILL.md）——跟 Claude Code 的 git submodule/marketplace 安装方式不同，Desktop 端是手动上传 UI，装好之后同样能用自然语言或 slash 指令触发。

常见错误

• ❌ Block theme 的 style.css 几乎是空的就被当成问题——block theme 本来就该用 theme.json 管样式，style.css 主要是主题头信息，内容极简是正确的
• ❌ Classic theme 没有 theme.json 就被要求补——classic theme 不靠 theme.json 也能正常运作，它只是给 block editor 支持用的可选项
• ❌ Hybrid theme 同时有 index.php 和 theme.json 被当成配置混乱——这是刻意的渐进式采用 block editor 的合理过渡形态，不是错误
• ❌ 模板部件没有在 theme.json 里注册就被判定为问题——模板部件靠文件名就能工作，注册只是为了增强 Site Editor 界面里的显示标签，不注册也不影响功能
• ❌ functions.php 里还留着 add_theme_support() 就被要求全部删掉——wp-block-styles、responsive-embeds、editor-styles 这几个 add_theme_support() 调用即使在 block theme 里也依然有效，theme.json 替代不了
• ❌ Block theme 没有 patterns/ 目录就被扣分——patterns 是可选项，主题完全可以依赖 WordPress.org 的 pattern 目录，不一定要自带
• 💡 发现模板转义问题，报告里提醒一句「安全问题，建议跑 /wp-sec-review」；functions.php 里出现插件式的 hook 逻辑，提醒跑 /wp-plugin-review；block 标记本身有问题，提醒跑 /wp-block-review——这个 skill 本身不深挖这三块

Sources

官方文档：

1. wordpress-skills（GitHub 仓库）— https://github.com/jorgerosal/wordpress-skills
2. wp-theme-development SKILL.md — https://github.com/jorgerosal/wordpress-skills/blob/main/claude-skills/wp-theme-development/SKILL.md