wp-patterns

WordPress 区块样板

所需输入

• 仓库根目录以及目标主题／插件目录。
• 样板类型：区段、起始页面、模板、模板部件或手动注册的插件样板。
• 主题／插件 slug、样板 slug 和文本域。
• 样板标题、分类、关键词、区块类型、模板类型以及插入器中的可见性。
• 如果目标 WordPress 版本与本仓库的兼容性约定不同，请提供该版本。
• 可用的 theme.json 预设：颜色、排版、间距、布局和渐变。
• 图片／图标的资源路径，包括资源是装饰性的还是信息性的。
• 验证环境：WordPress Playground、wp-env、本地 WordPress 或手动检查代码编辑器。
• 如果要更新现有样板：当前 slug、当前文件路径，以及已插入的现有内容是否必须保持兼容。
• 对于子主题：子主题 slug、文本域和资源根目录；除非明确有意，否则不要复用父主题的命名空间。

防护措施

1. 仅使用区块标记 — 所有视觉设计都通过区块注释属性和 preset slug 实现。不得使用内联 <style> 标签、自定义 CSS 类，也不得在区块包装器之外使用任意 HTML。阅读 references/design-with-tokens.md，了解核心原则。

2. 不使用 JavaScript — 样板是静态的 block markup。如需交互，请使用原生支持交互的区块（Navigation、Search、Query Loop）。

3. 注册时执行 PHP — 样板文件只在注册时执行一次 PHP，而不是在渲染时执行。阅读 references/pattern-registration.md，了解安全的输出函数、i18n 以及应避免使用的函数。

4. 嵌套有效 — 阅读 references/block-markup-reference.md，了解注释语法和嵌套规则。

5. 行为使用原生区块 — 使用 Query Loop、Search、Navigation、Social Icons 或现有表单区块，而不是自定义 PHP／HTML 行为。对于新闻简报、捐赠、付款或地图功能，请创建 CTA／占位内容，或使用现有区块／插件。

6. 本地资源 — 使用 get_theme_file_uri() 和 esc_url()；除非用户批准，否则不要使用外部占位 URL。阅读 references/pattern-registration.md 和 references/anti-patterns.md，查看示例。

流程

0) 初步检查并定位样板目标

1. 在仓库中工作时，运行初步检查：
   • node skills/wp-project-triage/scripts/detect_wp_project.mjs
2. 对于区块主题，定位目标主题根目录：
   • node skills/wp-block-themes/scripts/detect_block_themes.mjs
3. 确认样板应放在主题的 patterns/ 目录中，还是需要手动进行插件注册。
4. 如果存在多个主题／插件，请将所有更改限定在用户指定的目标范围内。

如果用户未提供所需输入，只能推断风险较低的默认值。在自创主题 slug、文本域、资源路径、自定义文章类型、分类法、活动日期字段或主题专属 preset 之前，务必先询问。如果缺少 theme.json 或无法验证预设，请使用保守的核心预设，或先询问是否可以使用主题专属的 slug。

**完成条件：**已确认目标主题／插件根目录、样板类型和注册路径。

1) 设计思考

在编写 block markup 前，仔细确定五项设计决策：用途、基调、空间构成、排版层级和配色策略。

阅读 references/design-with-tokens.md，了解决策框架和 preset 映射。

对于样板类型元数据（起始页面、模板样板、模板部件、查询循环、表单／CTA、比较／定价、社交／导航／搜索、404），请阅读 references/pattern-categories-and-types.md；使用 core/query 时，还要阅读其中的查询循环样板部分。

如果用户要求视觉上_独具特色_的构图，请阅读 references/visual-composition.md。

**完成条件：**已确定并记录全部五项设计决策，然后再编写标记。

2) 规划区块结构

编写标记前，先勾勒嵌套树。英雄区块模式示例：

Group (full-width, constrained layout, dark bg, vertical padding 80)
  Group (constrained inner, flex vertical, center align)
    Paragraph (uppercase label, small, letter-spacing, accent color)
    Heading (h2, xx-large, heading font, tight line-height)
    Paragraph (lead text, large, secondary color)
    Buttons (flex, center)
      Button (primary bg, base text)
      Button (outline style)

完成标准： 编写注释标签前，已勾勒嵌套树并明确层级结构。

3) 编写模式文件

组装 PHP 头部和 block markup。阅读 references/pattern-registration.md，了解头部字段、PHP 规则、手动注册和文件示例。

使用步骤 1 中选择的分类和模板类型。如果步骤 1 中尚未确定头部元数据，请阅读 references/pattern-categories-and-types.md。

区块标记主体：

• 遵循步骤 2 中的嵌套树
• 使用 preset slug 设置颜色、字号和间距
• 使用体现真实内容的占位文本，而非 “Lorem ipsum”

完成标准： PHP 头部和区块标记文件已编写完成。

4) 设计质量检查

根据 references/anti-patterns.md 中的设计质量检查清单进行检查。每一项都必须通过。

完成标准： 设计质量检查清单中的每一项都通过。

5) 技术验证

根据 references/anti-patterns.md 中的技术验证清单进行检查。每一项都必须通过。

完成标准： 技术验证清单中的每一项都通过。

验证

在真实的 WordPress 环境中测试该模式：

使用 WordPress Playground（推荐）：

npx @wp-playground/cli@latest server --auto-mount

挂载主题目录并验证：

• 该模式会显示在插入器指定的分类下
• 插入该模式时不会出现区块验证错误
• 桌面和移动设备宽度下的布局均能正确呈现
• 内容可编辑（文本、图像、按钮）
• 如果使用了 templateLock，锁定的元素无法编辑

对于模板模式，请验证站点编辑器会在预期的模板替换流程中提供该模式。如果使用了 Inserter: no，请确认该模式不会显示在常规插入器中，但仍可在预期位置使用。

手动检查：

• 将区块标记粘贴到 WordPress 的代码编辑器视图中
• 切换到可视化编辑器——区块应能正常解析，且不会提示“尝试恢复区块”
• 如果需要恢复，说明标记存在语法错误

如果模式变更涉及资源、生成文件或注册代码，请运行仓库现有的 lint、构建或测试命令。

更新现有模式时，请记住，插入的模式内容会复制到文章或模板中。更改模式文件不会追溯更新已插入的内容；更改区块名称或已保存的标记可能会导致新插入的内容出现恢复提示。

进行 PR 或软件包审查时，请确认差异仅涉及预期的模式文件、引用、脚本和评估场景。请勿将无关的仓库更新混入模式变更中。

故障模式／调试

首先查看 references/block-markup-reference.md、references/pattern-registration.md 和 references/anti-patterns.md。

常见故障：

• 插入器中缺少图案：检查是否包含必需的 Title、Slug 和 Categories 标头；确认文件位于 patterns/*.php 下；确认没有通过 Inserter: no 将其隐藏。
• 显示了错误的图案或图案被覆盖：检查 slug 是否冲突，并确保 slug 使用 theme-slug/pattern-name 或 plugin-slug/pattern-name 命名空间。
• 出现区块恢复提示：验证区块注释的嵌套、JSON 语法和闭合注释。
• 字符串未翻译或未转义：根据具体情况，将原始文本／PHP 输出替换为 esc_html_e()、esc_html__()、esc_attr_e()、esc_attr__() 或 esc_url()。
• 未加载翻译：验证文本域是否与目标主题／插件一致。
• 动态内容过时或不可用：移除依赖查询的 PHP（get_posts()、the_title()、wp_get_current_user()），改用查询循环等区块。
• 查询循环输出不完整：检查是否包含 core/post-template、文章标题／摘要／日期／图片区块、分页（如有需要）以及 core/query-no-results 备用内容。
• 归档／搜索／分类／作者上下文有误：使用继承的查询上下文，而不是硬编码的运行时 PHP。
• CPT 或活动列表有误：在生成图案前，确认文章类型 slug、分类法／日期字段以及插件提供的区块。
• 样式与主题不匹配：确认 preset slug 存在于 theme.json 中；除非有文档说明，否则避免使用不受支持的主题专属 slug。
• 无障碍问题：修正跳过的标题级别、信息性图片的空替代文本、对比度低的预设组合、含糊的按钮／链接文本、社交图标标签、搜索标签，以及仅靠颜色强调的内容。
• 手动注册失败：确认代码在 init 上运行、图案注册前已注册分类，并且图案内容仍为静态区块标记。

升级处理

遇到以下情况时，停止操作并寻求帮助或查阅权威文档：

• 无法验证主题专属的 preset slug、文本域、资源路径或图案分类。
• 颜色对比度、图片含义或内容层级需要人工进行设计／无障碍判断。
• 行为依赖的 WordPress／Gutenberg 版本不在此仓库的兼容性约定范围内。

示例提示词

阅读 references/example-prompts.md。