wp-theme-development

WordPress 主题开发审查技能

概述

针对 WordPress 6.6+ 的系统化主题开发审查，主要关注区块主题（全站编辑），并兼顾经典主题，为迁移提供指导。核心原则： WordPress 主题经历了范式转变——区块主题使用带有区块标记的 HTML 模板和 theme.json 管理全局设置与样式，取代 PHP 模板和 add_theme_support() 调用。theme.json v3 是设计配置的唯一事实来源。审查会验证 theme.json 结构、区块模板层级（templates/ 中的 HTML 文件）、模板部件（parts/）、全局样式、主题中的区块样板、子主题兼容性以及经典主题迁移到区块主题的机会。自动检测主题类型（区块/经典/混合/子主题/WordPress.org），并据此调整指导内容。审查结果按文件分组（PHP、HTML 模板、JSON 文件按实际路径混合排列），并标注行号、严重程度（CRITICAL/WARNING/INFO）以及 BAD/GOOD 代码对照。

注意： 此技能审查 PHP 文件（functions.php、经典模板）、HTML 区块模板文件（templates/、parts/）、JSON 文件（theme.json、样式变体）以及 PHP 样板文件（patterns/）。PHP 遵循 WordPress PHP 编码标准（括号内使用空格、使用 array() 而非 []、采用 Yoda 条件）。HTML 模板使用有效的区块标记。JSON 遵循 theme.json v3 架构。

适用场景

适用：

• 区块主题代码审查（theme.json、HTML 模板、模板部件）
• theme.json v3 架构验证和结构检查
• 模板层级审计（使用 .html 文件的区块主题、使用 .php 文件的经典主题）
• 模板部件审查（parts/header.html、parts/footer.html、parts/sidebar.html）
• 全局样式分析（调色板、排版、间距、布局设置）
• 样式变体验证（包含替代 theme.json 文件的 styles/ 目录）
• 主题中的区块样板审查（包含 PHP 文件的 patterns/ 目录）
• 子主题兼容性检查（区块或经典子主题）
• 经典主题迁移到区块主题的评估
• WordPress.org 主题提交准备情况（符合 Theme Check 要求）
• 检测区块主题中的硬编码样式
• 验证 useRootPaddingAwareAlignments 是否支持全宽对齐

不适用：

• 区块编辑器组件审查（React/JSX 区块请使用 wp-block-development）
• 插件架构审计（插件结构请使用 wp-plugin-development）
• 仅限安全性的审计（全面安全审查请使用 wp-security-review）
• 仅限性能的审计（性能分析请使用 wp-performance-review）
• WooCommerce 主题集成（如有可用版本，请使用 wp-woocommerce-dev）
• 视觉设计评估（此技能仅审查代码，不审查 UI/UX）

代码审查工作流

按照以下七步工作流系统化地审查主题：

1. 识别主题类型和上下文（THM-01）

   • 区块主题 → 包含 templates/index.html + theme.json + style.css
   • 经典主题 → 包含 index.php + style.css + functions.php（没有 templates/ 目录）
   • 混合主题 → 同时包含 index.php 和 theme.json（支持区块编辑器的经典主题）
   • 子主题 → style.css 中的 "Template:" 标头指向父主题
   • WordPress.org 提交 → 标准更严格（必须符合 Theme Check 要求）

   自动检测模式：

   # Block theme detection
   [ -f templates/index.html ] && [ -f theme.json ] && echo "Block theme"
   
   # Classic theme detection
   [ -f index.php ] && [ ! -d templates ] && echo "Classic theme"
   
   # Hybrid theme detection
   [ -f index.php ] && [ -f theme.json ] && [ ! -d templates ] && echo "Hybrid theme"
   
   # Child theme detection
   grep -q "^Template:" style.css && echo "Child theme"
   

2. 验证 theme.json 架构（THM-02、THM-03、THM-04、THM-05）

   • version 字段必须为 3（WP 6.6+）。v1 标记为 CRITICAL（已弃用），v2 标记为 WARNING（可升级）
   • 必需部分：settings、styles
   • 验证 settings 结构：color、typography、spacing、layout、border、shadow
   • 检查 v3 重大变更：defaultFontSizes 和 defaultSpacingSizes 默认均为 true（如果主题定义了自定义尺寸，必须显式设为 false）
   • 验证 templateParts 数组：name、title、area（header/footer/uncategorized）
   • 验证 customTemplates 数组：name、title、postTypes
   • 检查 $schema 字段（缺失时标记为 INFO，可增强 IDE 自动补全）
   • 当存在根填充时，验证 useRootPaddingAwareAlignments

3. 检查模板层级（THM-06、THM-07）

   • 区块主题：必须包含 templates/index.html，其他文件可选（home.html、front-page.html、single.html、page.html、archive.html、404.html、search.html）
   • 经典主题：必须包含 index.php，使用标准层级（header.php、footer.php、single.php、page.php、archive.php）
   • 验证模板文件使用正确的标记：区块主题使用 HTML 区块标记，经典主题使用 PHP 模板标签
   • 检查区块模板中是否存在硬编码样式（CRITICAL 反模式）
   • 验证模板中的模板部件引用

4. 检查模板部件（THM-08）

   • parts/ 目录结构：header.html、footer.html、sidebar.html
   • 验证 theme.json 中注册的 templateParts 与文件相符
   • 检查区域指定（header/footer/uncategorized）
   • 验证模板部件中的区块标记
   • 验证模板中是否通过 区块使用模板部件

5. 扫描 CRITICAL/WARNING/INFO 模式

   • **CRITICAL：**缺少必需文件（区块主题的 templates/index.html、经典主题的 index.php、style.css）、theme.json 版本或结构无效、缺少 style.css 标头字段、违反模板层级规则、区块主题使用硬编码内联样式，违背 theme.json 的用途
   • **WARNING：**theme.json v2（应升级到 v3）、style.css 中使用硬编码颜色/字体值而非 CSS 变量、存在根填充但缺少 useRootPaddingAwareAlignments、偏好使用区块模式却采用经典模式、区块主题中使用已弃用的 add_theme_support()
   • **INFO：**缺少样式变体、可以使用 theme.json 代替 add_theme_support()、字体可使用本地托管、缺少自定义模板注册

6. 根据上下文调整严重级别

   • 区块主题上下文：硬编码样式 = WARNING，缺少 theme.json 部分 = WARNING
   • 经典主题上下文：迁移机会 = INFO，缺少 theme.json = INFO
   • 混合主题上下文：提供渐进式采用指导，验证经典模式和 theme.json 模式
   • 子主题上下文：检查父主题兼容性和覆盖验证
   • WordPress.org 上下文：Theme Check 检查失败 = CRITICAL

7. 通过交叉引用生成报告

   • 按 FILE 分组（按路径混合列出 PHP、HTML、JSON 文件）
   • 包含行号、严重级别以及 BAD/GOOD 对照
   • 如果发现安全问题（模板转义）："检测到安全问题。运行 /wp-sec-review 进行全面的安全分析。"
   • 如果发现类似插件的模式（functions.php 钩子）："检测到插件架构模式。运行 /wp-plugin-review 获取插件开发指导。"
   • 如果发现区块标记问题："检测到区块标记问题。运行 /wp-block-review 获取区块开发指导。"

文件类型专项检查

theme.json (THM-02、THM-03、THM-04、THM-05)

version 字段：

• 严重：缺少 version 字段 → 主题无法正确加载
• 严重：version 为 1 → 已弃用，必须升级到 v3
• 警告：version 为 2 → 建议升级到 v3（defaultFontSizes 和 defaultSpacingSizes 存在破坏性变更）
• 模式："version": 3

$schema 字段：

• 信息：缺少 $schema → 无法在 IDE 中进行验证
• 模式："$schema": "https://schemas.wp.org/trunk/theme.json"

settings.color：

• 警告：缺少调色板 → 用户无法通过站点编辑器自定义颜色
• 警告：使用硬编码的颜色十六进制值，但未定义调色板
• 模式：color.palette 数组包含 slug、color、name
• 可用属性：palette、gradients、duotone、custom、defaultPalette、link、heading、button、caption

settings.typography：

• 警告：缺少 fontSizes → 用户无法自定义字号
• 严重（v3）：主题定义了 fontSizes，但缺少 "defaultFontSizes": false → WordPress 默认值会覆盖主题字号
• 警告：使用 Google Fonts CDN，而非本地字体文件（GDPR、性能）
• 模式：typography.fontSizes 数组；本地字体通过带有 fontFace 的 fontFamilies 定义
• 可用属性：fontSizes、fontFamilies、fluid、lineHeight、fontWeight、letterSpacing、textDecoration、textTransform、defaultFontSizes

settings.spacing：

• 警告：缺少 spacingSizes → 用户无法通过站点编辑器自定义间距
• 严重（v3）：主题定义了 spacingSizes，但缺少 "defaultSpacingSizes": false → WordPress 默认值会覆盖主题间距尺寸
• 模式：spacing.spacingSizes 数组包含 slug、size、name
• 可用属性：spacingSizes、padding、margin、blockGap、units、customSpacingSize、spacingScale、defaultSpacingSizes

settings.layout：

• 警告：缺少 contentSize 和 wideSize → 全宽区块可能无法正常工作
• 模式："contentSize": "640px", "wideSize": "1200px"

settings.useRootPaddingAwareAlignments：

• 警告：存在根级 padding，但缺少 useRootPaddingAwareAlignments → 全宽区块无法延伸到视口边缘
• 严重：useRootPaddingAwareAlignments 为 true，但 padding 使用 CSS 简写形式 → 必须使用对象表示法
• 模式：存在 styles.spacing.padding 时设为 true

styles 部分：

• 警告：使用硬编码值而非 CSS 变量 → 违背 theme.json 的用途
• 模式：使用 var(--wp--preset--color--primary)，而非 "#0073aa"
• 可用属性：color、typography、spacing、border、shadow、elements、blocks

templateParts 数组：

• 信息：未注册 templateParts → 模板部件仍可使用，但不会在界面中显示正确标签
• 模式：数组包含 name、title、area（header/footer/uncategorized）

customTemplates 数组：

• 信息：缺少 customTemplates → 用户无法在编辑器中选择自定义模板
• 模式：数组包含 name、title、postTypes

style.css (THM-09、THM-10)

必需的头部字段：

• 严重：缺少 "Theme Name" → WordPress 无法识别主题
• 警告：缺少 "Text Domain" → 国际化功能无法使用
• 警告：缺少 "Version" → 更新无法正常进行
• 信息：缺少 "Requires at least"、"Tested up to"、"Requires PHP" → 无法强制执行版本要求
• WordPress.org 要求：Theme Name、Theme URI、Author、Author URI、Description、Version、Requires at least、Tested up to、Requires PHP、License、License URI、Text Domain

区块主题样式模式：

• 警告：区块主题使用大量 CSS，而非 theme.json → 违背 FSE 的用途
• 信息：可以将硬编码的颜色／字体值移至 theme.json 预设中
• 模式：区块主题的 style.css 应尽量精简（仅包含元数据和关键 CSS），样式由 theme.json 提供

经典主题样式模式：

• 信息：经典主题可以采用 theme.json，以支持区块编辑器（混合方式）

子主题模式：

• 严重：子主题缺少 "Template:" 头部 → 无法继承父主题
• 警告：子主题的 template 与父主题目录名称不匹配 → 无法找到父主题

区块模板（templates/*.html）（THM-06、THM-11、THM-14）

必需模板：

• 严重：区块主题缺少 templates/index.html → 主题无法运行

模板文件命名：

• 信息：可添加特定模板（single.html、page.html、archive.html、404.html、search.html、home.html、front-page.html），以更好地覆盖模板层级

区块标记验证：

• 严重：区块注释语法无效 → 模板无法解析
• 警告：硬编码的内联 style 属性 → 无法发挥 theme.json 的作用，用户无法自定义
• 警告：使用硬编码的颜色十六进制值，而非 theme.json 预设值
• 警告：使用硬编码的像素字体大小，而非 theme.json 流式排版
• 模式：使用带有 theme.json 预设引用的区块属性，而非内联样式

模板部件用法：

• 警告：缺少模板部件引用（页眉/页脚）→ 用户通常期望采用标准结构
• 模式：``

useBlockProps 等效项：

• 信息：区块模板不需要像动态区块那样的包装器属性（静态 HTML）

模板部件（parts/*.html）（THM-08）

模板部件文件：

• 警告：theme.json 中注册了 templateParts，但文件缺失 → 网站编辑器中会出现 404
• 警告：模板部件文件存在，但未在 theme.json 中注册 → 不会在界面中显示正确的标签
• 模式：parts/header.html、parts/footer.html、parts/sidebar.html

区域指定：

• 警告：theme.json 中的模板部件区域与用法不一致 → 可能无法在正确的位置渲染
• 可用区域：header、footer、uncategorized（或 WP 6.0+ 中的自定义区域）

区块标记：

• 验证方式与区块模板相同：不使用硬编码样式，使用 theme.json 预设值

functions.php（THM-12、THM-13）

ABSPATH 检查：

• 警告：缺少 defined( 'ABSPATH' ) || exit; → 可能直接访问文件
• 交叉参考：安全性方面的深入内容请参阅 wp-security-review

区块主题设置：

• 警告：本应放在 theme.json 中的 add_theme_support() 调用 → 已弃用的模式
• 区块主题中可接受的 add_theme_support()：wp-block-styles、responsive-embeds、editor-styles（theme.json 无法替代这些功能）
• 模式：大多数 add_theme_support() 调用都应迁移到 theme.json 设置中

经典主题设置：

• 信息：经典主题可将 add_theme_support() 迁移到 theme.json，以采用混合方式
• 模式：调色板、字体大小、行高、间距 → theme.json 设置

主题钩子：

• 模式：使用 after_setup_theme 进行主题设置，使用 wp_enqueue_scripts 加载资源，使用 init 注册自定义文章类型
• 交叉参考：钩子系统模式请参阅 wp-plugin-development

资源入队：

• 警告：每个页面都入队资源，且未进行条件检查 → 性能问题
• 模式：使用条件标签（is_front_page、is_singular）或管理后台检查

区块样板（patterns/*.php）（THM-15、THM-16）

样板文件头部：

• 严重：样板文件缺少 Title 或 Slug 头部信息 → 无法注册
• 警告：样板 slug 未使用命名空间（themename/pattern-slug）→ 存在冲突风险
• 模式：PHP 文件中包含 Title、Slug、Categories、Description、Keywords、Block Types、Viewport Width 的注释块

样板文件结构：

• 警告：样板文件不含 PHP 标签 → 无法处理动态值
• 模式：使用 <?php ?> 标签编写 PHP 代码，然后编写区块标记

样板中的区块标记：

• 验证方式与模板相同：使用 theme.json 预设值，不使用硬编码样式
• 使用 PHP 函数处理动态值：get_theme_file_uri()、esc_url()、esc_html()、翻译函数

样板注册：

• 信息：patterns/ 目录中的样板会自动注册，无需手动调用 register_block_pattern()（仅适用于主题，不适用于插件）

样式变体 (styles/*.json) (THM-17、THM-18、THM-19)

变体文件结构：

• WARNING：样式变体缺少 version 字段 → 可能无法正确加载
• WARNING：样式变体缺少 title → UI 中将显示文件名
• 模式：包含 version、title、settings、styles 的 JSON 文件

变体命名：

• INFO：变体文件名将成为变体 slug（dark.json → "dark"），title 会覆盖显示名称
• 模式：使用描述性文件名（dark.json、minimal.json、high-contrast.json）

变体架构：

• WARNING：变体的 theme.json 结构无效 → 无法应用
• 模式：与 theme.json 使用相同的架构（settings、styles 部分），version 应与主 theme.json 一致

子主题 (THM-20)

子主题检测：

• 模式：style.css 中带有 "Template:" 标头

模板覆盖：

• WARNING：子主题的区块主题部件/header.html 未覆盖父主题 → 文件名必须完全匹配
• WARNING：子主题的 theme.json 未覆盖父主题的 templateParts → 必须复制并修改 templateParts 数组
• 模式：子主题文件通过完全匹配的文件名覆盖父主题文件

子主题兼容性：

• WARNING：子主题依赖的父主题模板部件可能会发生变化 → 覆盖方式脆弱
• INFO：子主题可以使用 unregister_block_pattern() 移除父主题样式

用于快速检测的搜索模式 (THM-21)

使用这些 rg 命令和 shell 检查快速扫描主题。按严重性整理。涵盖 PHP、HTML 模板和 JSON 文件。

严重模式

# Missing required files for block theme
[ ! -f templates/index.html ] && [ -f theme.json ] && echo "CRITICAL: Block theme missing templates/index.html"
[ ! -f theme.json ] && [ -d templates ] && echo "CRITICAL: templates/ exists but theme.json missing"

# Missing required files for classic theme
[ ! -f index.php ] && [ ! -d templates ] && echo "CRITICAL: Classic theme missing index.php"

# theme.json with invalid or missing version
test -f theme.json && ! rg -q "\"version\"" theme.json && echo "CRITICAL: theme.json missing version"
rg -n "\"version\": 1" theme.json  # Deprecated
rg -n "\"version\": [^23]" theme.json  # Invalid version

# Missing style.css required header
test -f style.css && ! rg -q "Theme Name:" style.css && echo "CRITICAL: style.css missing Theme Name header"

# v3 theme.json with custom fontSizes but missing defaultFontSizes: false
rg -n "\"fontSizes\"" theme.json
# Manual follow-up: if custom fontSizes are defined, confirm defaultFontSizes is explicitly false.

# v3 theme.json with custom spacingSizes but missing defaultSpacingSizes: false
rg -n "\"spacingSizes\"" theme.json
# Manual follow-up: if custom spacingSizes are defined, confirm defaultSpacingSizes is explicitly false.

# Child theme missing Template header
test -f style.css && ! rg -q "Template:" style.css && echo "CRITICAL: If this is a child theme, style.css is missing Template header"

警告模式

# theme.json version 2 (should upgrade to v3)
rg -n "\"version\": 2" theme.json

# Hardcoded inline styles in block templates
rg -n "style=\"" templates/ parts/ -g '*.html'

# Hardcoded color hex values in templates
rg -n "#[0-9a-fA-F]{6}" templates/ parts/ -g '*.html'

# Hardcoded pixel font sizes in templates
rg -n "font-size:\s*[0-9]+px" templates/ parts/ -g '*.html'

# Root padding without useRootPaddingAwareAlignments
rg -n "\"padding\"" theme.json
# Manual follow-up: if root padding is present, confirm useRootPaddingAwareAlignments is enabled.

# useRootPaddingAwareAlignments with CSS shorthand padding (won't work)
rg -n "useRootPaddingAwareAlignments.*true" theme.json
rg -n "\"padding\":\s*\"" theme.json

# Block theme with add_theme_support() that should be in theme.json
rg -n "add_theme_support.*editor-color-palette" functions.php
rg -n "add_theme_support.*editor-font-sizes" functions.php
rg -n "add_theme_support.*custom-line-height" functions.php
rg -n "add_theme_support.*custom-spacing" functions.php

# Missing ABSPATH check in functions.php
test -f functions.php && ! sed -n '1,10p' functions.php | rg -q "defined.*ABSPATH" && echo "WARNING: functions.php missing ABSPATH check in first 10 lines"

# Pattern file without required headers
rg -L "Title:" patterns -g '*.php'
rg -L "Slug:" patterns -g '*.php'

信息模式

# Missing $schema in theme.json
test -f theme.json && ! rg -q "\"\\$schema\"" theme.json && echo "INFO: theme.json missing \$schema"

# Missing style variations directory
[ ! -d styles ] && echo "INFO: Could add style variations in styles/"

# Missing block patterns directory
[ ! -d patterns ] && echo "INFO: Could add block patterns in patterns/"

# Missing templateParts registration in theme.json
test -f theme.json && ! rg -q "\"templateParts\"" theme.json && echo "INFO: theme.json missing templateParts registration"

# Missing customTemplates registration in theme.json
test -f theme.json && ! rg -q "\"customTemplates\"" theme.json && echo "INFO: theme.json missing customTemplates registration"

# Google Fonts CDN usage (could use local fonts)
rg -n "fonts.googleapis.com" .

# Classic theme without theme.json (could be hybrid)
[ -f index.php ] && [ ! -f theme.json ] && echo "INFO: Classic theme could add theme.json for block editor support"

**注意：**HTML 模板模式需要使用与 PHP 不同的正则表达式。模板使用 --include="*.html"，PHP 文件使用 --include="*.php"，theme.json 和变体使用 --include="*.json"。

主题上下文检测

根据检测到的主题类型提供上下文相关的审查说明：

区块主题

**结构：**templates/index.html + theme.json + style.css，可选的 parts/、patterns/、styles/ 审查重点：

• theme.json v3 验证是首要关注点
• 模板中的硬编码样式 = WARNING（违背 FSE 的目的）
• 模板层级完整性
• 存在内边距时使用 useRootPaddingAwareAlignments
• 将样式变体和样式作为增强机会 **常见错误：**缺少 useRootPaddingAwareAlignments、硬编码内联样式、theme.json v2 未迁移到 v3

经典主题

**结构：**index.php + style.css + functions.php、header.php、footer.php、模板文件 审查重点：

• 模板转义（交叉参考 wp-security-review）
• 经典模板层级
• 迁移到区块主题或混合方案的机会
• 建议采用 theme.json 以支持区块编辑器 **常见错误：**缺少转义、使用已弃用的模板标签、未使用 theme.json 来支持现代编辑器功能

混合主题

**结构：**index.php + theme.json + functions.php（使用 theme.json 的经典模板） 审查重点：

• 验证经典模式和 theme.json 模式
• 检查经典模板中的 CSS 变量用法
• 确认 theme.json 是否应用于区块内容
• 建议逐步迁移到区块模板 **常见错误：**theme.json 设置不会影响经典模板输出、误以为 theme.json 会为 PHP 模板设置样式

子主题（区块或经典）

**结构：**带有 "Template:" 标头的 style.css，可选的模板覆盖 审查重点：

• 与父主题的兼容性（模板文件名必须完全匹配）
• theme.json 覆盖模式（子主题必须复制并修改父主题的 templateParts）
• 模板部件覆盖
• 使用 unregister_block_pattern() 移除样式 **常见错误：**模板部件未覆盖（文件名错误）、theme.json 未覆盖父主题设置

WordPress.org 主题提交

结构： 任何主题类型，但标准更严格 审核重点：

• 符合 Theme Check 插件要求（所有错误均为严重问题）
• 必需文件：包含完整头部信息的 style.css、readme.txt、screenshot.png
• 许可证兼容性（GPL 或兼容 GPL）
• 不得包含混淆代码、不得回传数据、免费主题中不得有升级推销
• 为所有函数／类添加前缀 常见错误： 缺少 readme.txt、style.css 头部信息不完整、Theme Check 报错

快速参考：主题开发模式（THM-22、THM-23）

按关注点整理的常见主题模式。PHP 示例遵循 WordPress PHP 编码标准（括号内使用空格、使用 array() 而非 []、采用 Yoda 条件）。HTML 模板使用有效的区块标记。JSON 示例使用有效的 theme.json v3 语法。

theme.json v3 完整结构

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"settings": {
		"appearanceTools": true,
		"useRootPaddingAwareAlignments": true,
		"color": {
			"defaultPalette": false,
			"palette": [
				{
					"slug": "primary",
					"color": "#0073aa",
					"name": "Primary"
				},
				{
					"slug": "secondary",
					"color": "#005177",
					"name": "Secondary"
				},
				{
					"slug": "foreground",
					"color": "#333333",
					"name": "Foreground"
				},
				{
					"slug": "background",
					"color": "#ffffff",
					"name": "Background"
				}
			]
		},
		"typography": {
			"defaultFontSizes": false,
			"fluid": true,
			"fontFamilies": [
				{
					"fontFamily": "\"Inter\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif",
					"name": "Inter",
					"slug": "inter",
					"fontFace": [
						{
							"fontFamily": "Inter",
							"fontWeight": "400",
							"fontStyle": "normal",
							"src": [ "file:./assets/fonts/inter-regular.woff2" ]
						},
						{
							"fontFamily": "Inter",
							"fontWeight": "700",
							"fontStyle": "normal",
							"src": [ "file:./assets/fonts/inter-bold.woff2" ]
						}
					]
				}
			],
			"fontSizes": [
				{
					"slug": "small",
					"size": "0.875rem",
					"name": "Small"
				},
				{
					"slug": "medium",
					"size": "1rem",
					"name": "Medium"
				},
				{
					"slug": "large",
					"size": "1.5rem",
					"name": "Large"
				}
			]
		},
		"spacing": {
			"defaultSpacingSizes": false,
			"spacingSizes": [
				{
					"slug": "30",
					"size": "1rem",
					"name": "Small"
				},
				{
					"slug": "40",
					"size": "1.5rem",
					"name": "Medium"
				},
				{
					"slug": "50",
					"size": "2rem",
					"name": "Large"
				}
			],
			"units": [ "px", "rem", "vh", "vw", "%" ]
		},
		"layout": {
			"contentSize": "640px",
			"wideSize": "1200px"
		},
		"border": {
			"radius": true,
			"color": true,
			"style": true,
			"width": true
		}
	},
	"styles": {
		"color": {
			"background": "var(--wp--preset--color--background)",
			"text": "var(--wp--preset--color--foreground)"
		},
		"typography": {
			"fontFamily": "var(--wp--preset--font-family--inter)",
			"fontSize": "var(--wp--preset--font-size--medium)",
			"lineHeight": "1.6"
		},
		"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)"
			}
		},
		"elements": {
			"link": {
				"color": {
					"text": "var(--wp--preset--color--primary)"
				}
			},
			"heading": {
				"typography": {
					"fontWeight": "700",
					"lineHeight": "1.2"
				}
			}
		},
		"blocks": {
			"core/button": {
				"color": {
					"background": "var(--wp--preset--color--primary)",
					"text": "var(--wp--preset--color--background)"
				}
			}
		}
	},
	"customTemplates": [
		{
			"name": "page-no-title",
			"title": "Page Without Title",
			"postTypes": [ "page" ]
		}
	],
	"templateParts": [
		{
			"name": "header",
			"title": "Header",
			"area": "header"
		},
		{
			"name": "footer",
			"title": "Footer",
			"area": "footer"
		}
	]
}

区块模板结构（templates/single.html）

❌ 错误：硬编码内联样式会使 theme.json 失去作用

<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;">
		
	</div>
</main>

✅ 正确：使用区块属性和 theme.json 预设

<main class="wp-block-group">
	

	
	<div class="wp-block-group">
		
		
	</div>
	

	
</main>

模板部件结构（parts/header.html）

❌ 错误：硬编码颜色和间距

<div style="background: #ffffff; padding: 20px; border-bottom: 1px solid #cccccc;">
	<div style="max-width: 1200px; margin: 0 auto; display: flex; justify-content: space-between;">
		<h1 style="font-size: 24px; color: #0073aa;">Site Title</h1>
		<nav>Navigation</nav>
	</div>
</div>

✅ 正确：使用带有 theme.json 预设引用的区块属性

<div class="wp-block-group alignfull">
	
	<div class="wp-block-group">
		
		

		
	</div>
	
</div>

useRootPaddingAwareAlignments

❌ 错误：设置根元素内边距，却未启用 useRootPaddingAwareAlignments

{
	"version": 3,
	"styles": {
		"spacing": {
			"padding": {
				"left": "2rem",
				"right": "2rem"
			}
		}
	}
}

结果：全宽区块的左右边缘会出现留白

❌ 错误：为 useRootPaddingAwareAlignments 使用 CSS 简写

{
	"version": 3,
	"settings": {
		"useRootPaddingAwareAlignments": true
	},
	"styles": {
		"spacing": {
			"padding": "2rem"
		}
	}
}

结果：此方式无效，必须使用对象表示法

✅ 正确：为 useRootPaddingAwareAlignments 使用对象表示法

{
	"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)"
			}
		}
	}
}

从 theme.json v2 迁移到 v3

❌ 错误：升级版本，却未调整默认值

{
	"version": 3,
	"settings": {
		"typography": {
			"fontSizes": [
				{ "slug": "small", "size": "14px" },
				{ "slug": "medium", "size": "16px" }
			]
		}
	}
}

结果：WordPress 默认字号也会显示，且主题字号不会覆盖它们

✅ 正确：在 v3 中显式设置 defaultFontSizes: false

{
	"version": 3,
	"settings": {
		"typography": {
			"defaultFontSizes": false,
			"fontSizes": [
				{ "slug": "small", "size": "0.875rem", "name": "Small" },
				{ "slug": "medium", "size": "1rem", "name": "Medium" }
			]
		},
		"spacing": {
			"defaultSpacingSizes": false,
			"spacingSizes": [
				{ "slug": "30", "size": "1rem", "name": "Small" }
			]
		}
	}
}

主题中的区块样式（patterns/hero.php）

❌ 错误：样式缺少必需的头部信息

<?php
// Missing Title and Slug headers
?>

<div class="wp-block-cover">
	<h1>Welcome</h1>
</div>

✅ 正确：包含头部信息和动态值的完整样式

<?php
/**
 * Title: Hero Section
 * Slug: mytheme/hero
 * Categories: featured, banner
 * Keywords: hero, banner, header
 * Block Types: core/cover
 * Viewport Width: 1400
 * Description: Full-width hero section with heading and CTA
 */
?>

<div class="wp-block-cover alignfull">
	<span aria-hidden="true" class="wp-block-cover__background has-background-dim"></span>
	<img class="wp-block-cover__image-background" alt="" src="<?php echo esc_url( get_theme_file_uri( 'assets/images/hero.jpg' ) ); ?>" data-object-fit="cover" />

	<div class="wp-block-cover__inner-container">
		
		<h1 class="has-text-align-center"><?php echo esc_html_x( 'Welcome to Our Site', 'Pattern placeholder', 'mytheme' ); ?></h1>
		

		
		<div class="wp-block-buttons">
			
			<div class="wp-block-button">
				<a class="wp-block-button__link wp-element-button"><?php echo esc_html_x( 'Get Started', 'Pattern placeholder', 'mytheme' ); ?></a>
			</div>
			
		</div>
		
	</div>
</div>

样式变体（styles/dark.json）

❌ 错误：变体缺少版本或标题

{
	"settings": {
		"color": {
			"palette": [
				{ "slug": "background", "color": "#1a1a1a" }
			]
		}
	}
}

✅ 正确：包含版本和标题的完整变体

{
	"version": 3,
	"title": "Dark Mode",
	"settings": {
		"color": {
			"palette": [
				{
					"slug": "foreground",
					"color": "#ffffff",
					"name": "Foreground"
				},
				{
					"slug": "background",
					"color": "#1a1a1a",
					"name": "Background"
				},
				{
					"slug": "primary",
					"color": "#3dadff",
					"name": "Primary"
				}
			]
		}
	},
	"styles": {
		"color": {
			"background": "var(--wp--preset--color--background)",
			"text": "var(--wp--preset--color--foreground)"
		}
	}
}

区块主题的 functions.php

❌ 错误：使用 add_theme_support()，而非 theme.json

<?php
function mytheme_setup() {
	add_theme_support( 'align-wide' );
	add_theme_support( 'custom-line-height' );
	add_theme_support( 'custom-spacing' );
	add_theme_support( 'editor-color-palette', array(
		array(
			'name'  => 'Primary',
			'slug'  => 'primary',
			'color' => '#0073aa',
		),
	) );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

✅ 正确：精简的 functions.php，在 theme.json 中设置配置

<?php
/**
 * Theme setup and initialization
 */

defined( 'ABSPATH' ) || exit;

/**
 * Theme setup
 */
function mytheme_setup() {
	// Still valid in block themes
	add_theme_support( 'wp-block-styles' );
	add_theme_support( 'responsive-embeds' );
	add_theme_support( 'editor-styles' );

	// Load editor stylesheet
	add_editor_style( 'style.css' );

	// Internationalization
	load_theme_textdomain( 'mytheme', get_template_directory() . '/languages' );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

/**
 * Enqueue additional scripts (if needed)
 */
function mytheme_enqueue_assets() {
	// Only if theme needs custom JS
	if ( is_front_page() ) {
		wp_enqueue_script(
			'mytheme-interactions',
			get_theme_file_uri( '/assets/js/interactions.js' ),
			array(),
			wp_get_theme()->get( 'Version' ),
			true
		);
	}
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_assets' );

从经典主题迁移到区块主题

❌ 错误：经典主题方式（已不建议用于区块主题）

<?php
// functions.php in classic theme
function classictheme_setup() {
	add_theme_support( 'custom-logo' );
	add_theme_support( 'custom-header' );
	add_theme_support( 'custom-background' );
	add_theme_support( 'editor-color-palette', array(
		array( 'name' => 'Primary', 'slug' => 'primary', 'color' => '#0073aa' ),
	) );
	add_theme_support( 'editor-font-sizes', array(
		array( 'name' => 'Small', 'size' => 14, 'slug' => 'small' ),
	) );
}
add_action( 'after_setup_theme', 'classictheme_setup' );

✅ 正确：通过 theme.json 使用区块主题方式

{
	"version": 3,
	"settings": {
		"layout": {
			"contentSize": "640px",
			"wideSize": "1200px"
		},
		"typography": {
			"defaultFontSizes": false,
			"fontSizes": [
				{
					"slug": "small",
					"size": "0.875rem",
					"name": "Small"
				}
			]
		},
		"color": {
			"defaultPalette": false,
			"palette": [
				{
					"slug": "primary",
					"color": "#0073aa",
					"name": "Primary"
				}
			]
		}
	}
}

子主题模式

❌ 错误：子主题的 style.css 缺少 Template 头部信息

/*
Theme Name: My Child Theme
Description: A child theme
Author: Author Name
*/

结果：WordPress 无法识别父主题

✅ 正确：完整的子主题 style.css

/*
Theme Name: My Child Theme
Template: parent-theme-folder
Description: A child theme extending Parent Theme
Author: Author Name
Author URI: https://example.com
Version: 1.0.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-child-theme
*/

子主题模板部件覆盖：

parent-theme/
├── parts/
│   └── header.html

child-theme/
├── style.css (with Template: parent-theme)
└── parts/
    └── header.html  ← Must match filename exactly to override

严重性定义（THM-23）

严重性	定义	示例
CRITICAL	主题无法运行，或遭到 WordPress.org 拒绝	缺少必需文件（区块主题的 templates/index.html、经典主题的 index.php，以及所有主题的 style.css）、theme.json 版本无效（v1 已弃用）、style.css 缺少 "Theme Name" 标头、违反模板层级规则、子主题缺少 "Template:" 标头、theme.json v3 使用自定义 fontSizes/spacingSizes，但缺少 defaultFontSizes/defaultSpacingSizes: false（WordPress 默认值会覆盖主题设置）、useRootPaddingAwareAlignments 使用 CSS 简写形式的 padding（必须使用对象表示法）、模式文件缺少 Title 或 Slug 标头
WARNING	主题可以运行，但存在质量或兼容性问题	theme.json v2（应升级到 v3 以支持破坏性变更）、区块主题模板中包含硬编码样式（内联 style 属性、硬编码十六进制颜色、像素字体大小）、存在根级内边距但缺少 useRootPaddingAwareAlignments（全宽区块无法延伸到边缘）、使用经典模式而非首选的区块模式、区块主题中调用已弃用的 add_theme_support()（editor-color-palette、editor-font-sizes、custom-line-height、custom-spacing 应放在 theme.json 中）、functions.php 缺少 ABSPATH 检查、模板部件文件未在 theme.json 中注册、硬编码的 WordPress 路径（/wp-content/themes/）
INFO	最佳实践改进或优化机会	theme.json 缺少 $schema（IDE 验证）、缺少样式变体目录、缺少区块模式目录、缺少 templateParts 或 customTemplates 注册、使用 Google Fonts CDN 而非本地字体（GDPR、性能）、经典主题没有 theme.json（可改为混合主题）、可添加特定模板（single.html、page.html）以完善层级、子主题可使用 unregister_block_pattern() 移除父主题模式、style.css 缺少版本要求（Requires at least、Tested up to、Requires PHP）

输出格式（THM-24）

按文件归类报告发现（PHP、HTML 模板、JSON 文件按实际文件路径混排），并注明行号和严重性标签。每项发现都使用 BAD/GOOD 代码对。

# WordPress Theme Review: my-theme

## Theme Type: Block Theme
**Detected:** templates/index.html + theme.json + style.css

## FILE: theme.json

### Line 2: WARNING - theme.json version 2 (upgrade to v3)
theme.json v2 still works but v3 is recommended for WP 6.6+. Breaking changes: defaultFontSizes and defaultSpacingSizes now default to true.

❌ **BAD:**
```json
{
	"version": 2
}

✅ GOOD:

{
	"version": 3,
	"settings": {
		"typography": {
			"defaultFontSizes": false,
			"fontSizes": [ /* custom sizes */ ]
		}
	}
}

第 45 行：WARNING - 缺少 useRootPaddingAwareAlignments

存在根级内边距，但未设置 useRootPaddingAwareAlignments。全宽区块无法延伸到视口边缘。

❌ BAD:

{
	"styles": {
		"spacing": {
			"padding": { "left": "2rem", "right": "2rem" }
		}
	}
}

✅ GOOD:

{
	"settings": {
		"useRootPaddingAwareAlignments": true
	},
	"styles": {
		"spacing": {
			"padding": {
				"top": "2rem",
				"right": "2rem",
				"bottom": "2rem",
				"left": "2rem"
			}
		}
	}
}

文件：templates/single.html

第 8 行：WARNING - 内联样式已硬编码

内联 style 属性违背了 theme.json 的设计目的，用户无法通过站点编辑器进行自定义。

❌ BAD:

<div style="max-width: 1200px; padding: 2rem;">

✅ GOOD:

<div class="wp-block-group">

文件：functions.php

第 1 行：WARNING - 缺少 ABSPATH 检查

在文件顶部添加 ABSPATH 检查，以防止直接访问。

❌ BAD:

<?php
function mytheme_setup() {

✅ GOOD:

<?php
defined( 'ABSPATH' ) || exit;

function mytheme_setup() {

第 15 行：WARNING - add_theme_support() 在区块主题中已弃用

对于区块主题，应将 editor-color-palette 放在 theme.json 中。

❌ BAD:

add_theme_support( 'editor-color-palette', array(
	array( 'name' => 'Primary', 'slug' => 'primary', 'color' => '#0073aa' ),
) );

✅ GOOD:

// In theme.json:
{
	"settings": {
		"color": {
			"palette": [
				{ "slug": "primary", "color": "#0073aa", "name": "Primary" }
			]
		}
	}
}

文件：style.css

第 1 行：INFO - 缺少版本要求

添加 Requires at least、Tested up to、Requires PHP，以执行版本要求。

/*
Theme Name: My Theme
Version: 1.0.0
Requires at least: 6.6
Tested up to: 6.7
Requires PHP: 7.4
*/

摘要

问题总数：6

• CRITICAL：0
• WARNING：4（需要改进质量或兼容性）
• INFO：2（最佳实践优化）

升级建议： 将 theme.json 更新到 v3，并明确设置 defaultFontSizes 和 defaultSpacingSizes。 硬编码样式： 在模板中发现硬编码样式；将其迁移到 theme.json 预设，以便用户自定义。 安全提示： 缺少 ABSPATH 检查。运行 /wp-sec-review 进行全面安全分析。 插件提示： 检测到 functions.php 钩子。运行 /wp-plugin-review 查看插件开发模式。

## Common Mistakes (THM-25)

Patterns that look like issues but are NOT problems:

| Pattern | Why It's NOT a Problem | Context |
|---------|------------------------|---------|
| **Block theme with minimal style.css** | Block themes use theme.json for styling, style.css is primarily metadata | Correct for block themes - style.css contains theme header, minimal CSS |
| **Classic theme without theme.json** | Classic themes work without theme.json, optional for block editor support | Valid classic theme - theme.json is optional for hybrid approach |
| **Hybrid theme with both index.php and theme.json** | Intentional pattern for incremental block editor adoption | Valid hybrid approach - theme.json enhances block editor, classic templates still work |
| **Template part without theme.json registration** | Template parts work by filename, registration is for UI labels only | Works correctly - registration enhances Site Editor UI but not required |
| **Style variation missing some settings sections** | Variations only need to override specific settings, not full schema | Intentional - variations merge with main theme.json |
| **Block template without template-part blocks** | Not all templates need header/footer, valid for custom layouts | Intentional for special templates (404, search results without chrome) |
| **functions.php with add_theme_support() in block theme** | Some add_theme_support() calls are still valid (wp-block-styles, responsive-embeds, editor-styles) | Valid - these can't be replaced by theme.json |
| **Pattern file with only static markup (no PHP)** | If pattern doesn't need dynamic values, static HTML is fine | Valid - PHP optional for static patterns |
| **Child theme without functions.php** | Child themes don't need functions.php if only overriding styles/templates | Valid minimal child theme - functions.php is optional |
| **Block theme without patterns/ directory** | Patterns are optional, not all themes need bundled patterns | Valid - themes can rely on WordPress.org pattern directory |
| **Missing viewScript in theme** | Themes typically don't need frontend JavaScript, unlike blocks | Expected - most themes are HTML/CSS only |
| **CSS variables in style.css referencing theme.json** | Correct usage - theme.json generates CSS variables that style.css can reference | Intentional integration between theme.json and style.css |

## Version Compatibility Reference

Quick reference for WordPress version requirements:

| Feature | WordPress Version | Notes |
|---------|-------------------|-------|
| Block themes (FSE) | 5.9+ | Full Site Editing stable release |
| theme.json v1 | 5.8+ | Initial theme.json support |
| theme.json v2 | 5.9+ | Expanded settings and styles options |
| theme.json v3 | 6.6+ | Breaking changes: defaultFontSizes and defaultSpacingSizes defaults |
| useRootPaddingAwareAlignments | 6.1+ | Full-width alignment with root padding |
| Template parts areas | 6.0+ | header, footer, uncategorized areas |
| fontFace support in theme.json | 6.0+ | Local font hosting via theme.json |
| Block theme patterns (patterns/) | 6.3+ | Auto-registration of PHP pattern files |
| Navigation block | 5.9+ | Replaces wp_nav_menu() in block themes |
| Site Editor | 5.9+ | Full Site Editing interface |
| Global Styles | 5.9+ | User customization of theme.json via UI |
| Style variations | 6.0+ | Alternate theme.json files in styles/ |

## Deep-Dive References

For advanced theme development patterns, load these companion reference documents:

| Task | Reference to Load |
|------|-------------------|
| theme.json v3 complete schema, all sections explained (settings, styles, templateParts, customTemplates, patterns), property catalog with valid values, v2→v3 migration notes, common mistakes, WordPress.org requirements | `references/theme-json-guide.md` |
| Template hierarchy for both classic and block themes side-by-side, template parts and areas, conditional tags, get_template_part() for classic, block markup in HTML templates, custom templates registration | `references/template-patterns.md` |
| Full Site Editing comprehensive guide: site editor workflow, global styles UI mapping to theme.json, style variations creation, block patterns in themes (patterns/ directory), navigation configuration, font management, layout system (contentSize, wideSize, root padding) | `references/fse-guide.md` |
| Step-by-step classic-to-block migration: functions.php → theme.json mapping table, template.php → template.html conversion, sidebar widgets → template parts, Customizer → global styles, add_theme_support → theme.json equivalents, incremental hybrid adoption path | `references/classic-to-block-guide.md` |

**Note:** Reference docs provide deep-dive content. This SKILL.md is self-sufficient for standard theme reviews.

**Security crossover:** When encountering security-relevant patterns (template escaping in classic themes, child theme security, sanitization in theme customizer), this skill provides brief reminders but defers to wp-security-review for comprehensive security analysis. For detailed security patterns, use `/wp-sec-review` command.

**Plugin crossover:** When encountering plugin-level patterns (functions.php hooks like after_setup_theme, wp_enqueue_scripts, init for CPT registration), this skill provides brief mentions but defers to wp-plugin-development for plugin architecture depth. For detailed plugin patterns, use `/wp-plugin-review` command.

**Block crossover:** When encountering block development patterns (block patterns registration in themes vs plugins, block markup in templates, block supports defined in theme.json), this skill provides brief context but defers to wp-block-development for block-specific depth. For detailed block patterns, use `/wp-block-review` command.