wp-theme-dev

WordPress 主题开发

概述

创建可用于生产环境的 WordPress 主题，使其符合官方 WordPress 编码标准、WordPress.org 主题审核要求、WCAG 2.1 AA 级无障碍标准和现代 Web 开发最佳实践。此技能生成的每个主题都具备无障碍性、安全性、可翻译性和高性能，并已做好提交至 WordPress.org 的准备。

快速入门工作流

1. 阅读参考资料 — 编写任何代码之前，先阅读相关参考文件：
   • references/block-theme-architecture.md — 区块主题结构、theme.json、模板和模式
   • references/classic-theme-architecture.md — 经典主题结构、模板层级和 The Loop
   • references/accessibility.md — WCAG 2.1 AA 要求、WordPress 无障碍就绪标准
   • references/review-requirements.md — WordPress.org 主题审核清单（14 个类别）
2. 确定主题类型 — 询问用户想要区块主题（推荐）、经典主题还是子主题
3. 收集需求 — 设计目标、配色方案、排版和所需功能
4. 搭建框架 — 生成目录结构、必需文件和 theme.json
5. 构建模板和模式 — 将每个模板/模式创建为单独的文件
6. 生成 readme.txt — 始终包含符合 WordPress.org 要求的 readme.txt
7. 交付 — 询问用户希望下载文件，还是使用自定义路径

核心原则 — 始终遵循

1. 默认使用区块主题

除非用户明确要求经典主题，否则始终构建区块主题（全站编辑）。区块主题：

• 使用 HTML 模板文件（而非 PHP 模板文件）
• 通过 theme.json 配置设计（而非 PHP/CSS）
• 支持使用站点编辑器进行完整的可视化编辑
• 使用区块模式创建可重复使用的布局
• 使用模板部件创建页眉、页脚和侧边栏

仅当用户明确要求，或需要只有经典主题才支持的功能时，才构建经典主题。

2. 保持 functions.php 简洁

functions.php 文件应仅包含：

• 主题设置（after_setup_theme 钩子）——声明主题功能支持
• 资源入队（wp_enqueue_scripts 钩子）
• 注册区块模式、模式类别和区块样式
• 注册导航菜单（经典主题）
• 注册小工具区域（经典主题）
• 从 inc/ 目录加载其他 PHP 文件

切勿将冗长的逻辑、HTML 输出或复杂功能直接写入 functions.php。 将其他功能拆分到 inc/ 目录中的文件。

3. 无障碍 — 不容妥协

每个主题都必须符合 WCAG 2.1 AA 级和 WordPress 无障碍要求。这不是可选项。

请阅读 references/accessibility.md，了解完整要求。以下是关键必备事项：

跳过链接： 第一个可聚焦元素，在获得焦点时显示，并跳转到主要内容。

键盘导航： 所有交互元素都必须可通过键盘访问和操作。所有可聚焦元素都必须有可见的焦点指示器。焦点顺序必须遵循逻辑阅读顺序。

语义化 HTML： 使用适当的 HTML5 地标元素（<header>、<main>、<nav>、<aside>、<footer>）。使用 ARIA 地标角色进行补充。标题层级必须正确（每页一个 H1，不得跳过级别）。

颜色对比度： 所有文本与背景的对比度必须达到 4.5:1（大号文本，即 18px 及以上的粗体文本或 24px 及以上的常规文本，须达到 3:1）。UI 组件和焦点指示器的对比度须达到 3:1。

内容链接： 正文内容中的链接必须添加下划线。仅使用粗体、斜体或颜色区分不可接受。

表单： 所有表单输入都必须有显式的 <label> 元素。不得仅使用占位符作为标签。错误状态必须能被屏幕阅读器感知。

图片： 所有 <img> 标签都必须有意义明确的 alt 属性。装饰性图片使用 alt=""。

屏幕阅读器文本： 使用 .screen-reader-text 类，为视觉上隐藏但可访问的文本提供支持。适用于“阅读更多”链接、仅图标按钮和重复链接文本。

重复链接文本： “阅读更多”链接必须包含文章标题（可以在视觉上隐藏）。

媒体： 嵌入的媒体不得自动播放。所有媒体都必须提供控件。

4. 安全

• 转义所有输出：esc_html()、esc_attr()、esc_url()、wp_kses_post()
• 清理所有输入：sanitize_text_field()、absint() 等
• 所有表单提交都必须使用 nonce
• 在执行特权操作前进行验证并检查权限
• 不得使用 eval()、对用户数据调用 base64_decode()，也不得在未经清理的情况下直接使用 $_GET/$_POST

5. WordPress 编码规范

• 所有函数、类、钩子和句柄都必须添加唯一的主题前缀（至少 4 个字符）
• 所有面向用户的字符串都必须可翻译：__()、_e()、esc_html__()、esc_html_e() 等
• 文本域必须与主题 slug 一致
• 使用 wp_enqueue_script() / wp_enqueue_style()，不得硬编码 <script> 或 <link> 标签
• 使用 WordPress 捆绑的库（jQuery 等），不得捆绑自己的副本
• 使用压缩文件时，必须包含原始源文件
• 启用 WP_DEBUG 时不得出现 PHP 错误、警告或提示
• 不得使用已弃用的函数或常量

6. 符合 WordPress.org 主题审核要求

每个主题都必须符合全部 14 个审核类别。请阅读 references/review-requirements.md。

关键规则：

• 所有代码、图片、字体和资源都必须使用 GPLv2 或更高版本的许可证
• 在 readme.txt 中为所有捆绑资源注明版权和许可证信息
• 未经用户明确同意，不得使用跟踪功能或远程资源（Google Fonts 除外）
• 不得包含插件范畴的功能（CPT、短代码、SEO、分析、联系表单）
• 不得劫持管理后台；通知必须可关闭
• 激活主题时不得重定向
• 不得移除或隐藏管理工具栏
• 主题名称不得使用“WordPress”“Theme”或“Twenty*”
• 截图必须展示主题的实际效果，不得用作广告
• readme.txt 必须包含所有必需的标题

7. 现代 CSS 与性能

• 使用 CSS 自定义属性（变量）实现主题样式，并与 theme.json 预设保持一致
• 使用现代布局：CSS Grid 和 Flexbox（不得使用浮动进行布局）
• 使用 clamp() 实现流式自适应排版和间距
• 使用逻辑属性（margin-inline、padding-block）支持 RTL
• 采用移动优先的响应式设计，并使用 min-width 媒体查询
• 尽量减少阻塞渲染的资源
• 对首屏以下的图片和 iframe 使用 loading="lazy"
• 自定义字体使用 font-display: swap
• 为保护隐私和提升性能，优先使用系统字体栈或本地托管字体，而不是 Google Fonts

主题类型参考

用户需求	主题类型	关键参考
区块主题 / FSE 主题	区块主题	references/block-theme-architecture.md
经典 PHP 主题	经典主题	references/classic-theme-architecture.md
修改现有主题	子主题	根据父主题类型选择对应的参考
混合方案	经典 + 区块特性	两份参考

命名约定

根据用户提供的主题名称推导所有名称：

元素	约定	示例（主题："Starter Blue"）
主题 slug	小写加连字符	starter-blue
文本域	与 slug 相同	starter-blue
函数前缀	小写加下划线（4+ 字符）	stbl_
常量前缀	大写加下划线	STBL_
类前缀	首字母大写加下划线	Starter_Blue_
句柄名称	slug 前缀	starter-blue-style
模式分类	slug 前缀	starter-blue
区块样式名称	slug 前缀	starter-blue/card-shadow

选择一个从主题名称推导出的简短前缀（4+ 字符）。

交付

构建主题后：

1. 询问用户希望将文件放在何处：
   • 下载： 复制到 /mnt/user-data/outputs/{theme-slug}/ 并提供下载
   • 自定义路径： 写入用户指定的路径
2. 始终包含 readme.txt 和 style.css，并带有所有必需的头部信息
3. 提供生成文件的简要摘要
4. 如果使用构建流程（带自定义区块的区块主题），请注明需要运行 npm install && npm run build

交付前检查清单

• style.css 包含所有必需的标头（主题名称、作者、版本、许可证等）
• readme.txt 存在且内容完整，并包含资源致谢
• 所有输出均已转义（esc_html、esc_attr、esc_url、wp_kses_post）
• 所有输入均已清理
• 所有字符串均可翻译，并使用正确的文本域
• 所有函数／类／句柄均带有前缀（4 个或更多字符）
• 存在跳过链接，且它是第一个可聚焦元素，并在获得焦点时可见
• 所有交互元素均支持键盘导航
• 所有可聚焦元素均具有可见的焦点指示器
• 标题层级正确（仅有一个 H1，且不跳过层级）
• 内容链接带下划线
• 颜色对比度符合 WCAG 2.1 AA（文本为 4.5:1，大号文本／UI 为 3:1）
• 所有图片均具有适当的 alt 属性
• 存在 ARIA 地标；重复地标具有唯一标签
• “阅读更多”链接包含文章标题（screen-reader-text）
• 表单具有明确的 <label> 元素
• 开启 WP_DEBUG 时无 PHP 错误／警告／通知
• 无已弃用函数
• 未捆绑 WP 默认库
• 无属于插件范畴的功能
• 未经同意不加载远程资源
• 激活时不重定向到管理页面
• 资源均通过正确的方式加入队列（未硬编码）
• 响应式设计在所有断点下均正常
• 通过逻辑属性或 RTL 样式表支持 RTL
• 许可证为 GPLv2 或更高版本
• 截图为 1200×900，且展示主题的实际输出