wp-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WordPress Block Patterns

WordPress 区块模式

When to use

适用场景

Use this skill when creating, updating, or reviewing WordPress block patterns such as:

filesystem patterns in
```
patterns/*.php
```
starter page patterns for page/post content
template patterns using
```
Template Types
```
template part patterns for headers, footers, sidebars, or other parts
pattern category, keyword, inserter, block type, and template type metadata
pattern markup validation, escaping, i18n, accessibility, or design quality improvements

Generate production-grade patterns that are technically correct, design-distinctive, theme-compatible, and accessible. If the user is building a custom block, changing

block.json

, or adding dynamic rendering, use

wp-block-development

instead. If the user needs frontend interactivity, use

wp-interactivity-api

当你创建、更新或审核以下WordPress区块模式时，可使用本技能：

```
patterns/*.php
```
中的文件系统模式
页面/文章内容的起始页模式
使用「模板类型」的模板模式
页眉、页脚、侧边栏或其他部件的模板部件模式
模式分类、关键词、插入器、区块类型和模板类型元数据
模式标记验证、转义、国际化、无障碍访问或设计质量优化

生成符合生产环境标准的模式，确保技术规范、设计独特、兼容主题且支持无障碍访问。如果用户正在构建自定义区块、修改

block.json

或添加动态渲染，请使用

wp-block-development

技能；如果用户需要前端交互功能，请使用

wp-interactivity-api

技能。

Inputs required

所需输入

Repo root and target theme/plugin directory.
Pattern type: section, starter page, template, template part, or manually registered plugin pattern.
Theme/plugin slug, pattern slug, and text domain.
Pattern title, categories, keywords, block types, template types, and inserter visibility.
Target WordPress version if it differs from this repo's compatibility contract.
Available
```
theme.json
```
presets for colors, typography, spacing, layout, and gradients.
Asset paths for images/icons, including whether assets are decorative or informational.
Verification environment: WordPress Playground, wp-env, local WordPress, or manual Code Editor check.
If updating an existing pattern: current slug, current file path, and whether existing inserted content must remain compatible.
For child themes: child theme slug, text domain, and asset root; do not reuse the parent namespace unless explicitly intended.

代码库根目录和目标主题/插件目录
模式类型：区块、起始页、模板、模板部件或手动注册的插件模式
主题/插件标识（slug）、模式标识和文本域
模式标题、分类、关键词、区块类型、模板类型和插入器可见性
目标WordPress版本（若与代码库兼容协议不同）
```
theme.json
```
中可用的颜色、排版、间距、布局和渐变预设
图片/图标资源路径，包括资源是装饰性还是信息性
验证环境：WordPress Playground、wp-env、本地WordPress或手动代码编辑器检查
若更新现有模式：当前标识、当前文件路径，以及是否需保持现有插入内容的兼容性
若为子主题：子主题标识、文本域和资源根目录；除非明确指定，否则不要复用父主题命名空间

Guardrails

约束规则

Before writing any pattern, internalize these constraints:

Block markup only — all visual design is expressed through block comment attributes and theme.json presets. No inline
```
<style>
```
tags, no custom CSS classes, no arbitrary HTML outside of block wrappers.
No JavaScript — patterns are static block markup. For interactivity, use blocks that natively support it (Navigation, Search, Query Loop). Never inject
```
<script>
```
tags.
PHP runs at
init
, not render — pattern files execute PHP once during registration. Never use query-dependent functions (
```
get_posts()
```
,
```
the_title()
```
,
```
wp_get_current_user()
```
). Safe:
```
esc_html_e()
```
,
```
get_theme_file_uri()
```
. Read
```
references/pattern-registration.md
```
for registration-time PHP constraints.
Always escape — every PHP output must use
```
esc_html__()
```
,
```
esc_attr__()
```
, or
```
esc_url()
```
. No raw
```
echo
```
of user-facing strings. Read
```
references/pattern-registration.md
```
for safe PHP output functions.
Always i18n — every user-visible string must be wrapped in a translation function with the theme/plugin text domain. Use
```
esc_html_e()
```
(echo + escape + translate) or
```
esc_html__()
```
(return + escape + translate). Read
```
references/pattern-registration.md
```
for text domain and i18n examples.
Prefer presets over hardcoded values — use
```
"backgroundColor":"primary"
```
not
```
"style":{"color":{"background":"#0073aa"}}
```
. Presets adapt to theme changes and style variations.
Valid nesting — every opening
```

```
must have a matching
```

```
. Nesting must be properly ordered. Self-closing blocks use
```

```
.
Use native blocks for behavior — use Query Loop, Search, Navigation, Social Icons, or an existing form block instead of custom PHP/HTML behavior. For newsletter, donation, payment, or map behavior, create a CTA/placeholder or use an existing block/plugin; do not invent forms, iframes, scripts, or third-party processing.
Prefer local assets — use theme/plugin assets with
```
get_theme_file_uri()
```
and
```
esc_url()
```
. Avoid external placeholder image URLs unless the user explicitly approves them.

Reference:

references/block-markup-reference.md

for syntax,

references/anti-patterns.md

for what to avoid.

在编写任何模式前，请牢记以下约束：

仅使用区块标记 — 所有视觉设计通过区块注释属性和theme.json预设实现。禁止使用内联
```
<style>
```
标签、自定义CSS类或区块包装器外的任意HTML。
禁止JavaScript — 模式为静态区块标记。如需交互功能，请使用原生支持交互的区块（导航、搜索、查询循环）。切勿注入
```
<script>
```
标签。
PHP仅在
init
阶段运行，而非渲染阶段 — 模式文件仅在注册时执行一次PHP。禁止使用依赖查询的函数（
```
get_posts()
```
、
```
the_title()
```
、
```
wp_get_current_user()
```
）。安全函数示例：
```
esc_html_e()
```
、
```
get_theme_file_uri()
```
。请阅读
```
references/pattern-registration.md
```
了解注册阶段的PHP约束。
始终进行转义 — 所有PHP输出必须使用
```
esc_html__()
```
、
```
esc_attr__()
```
或
```
esc_url()
```
。禁止直接
```
echo
```
面向用户的字符串。请阅读
```
references/pattern-registration.md
```
了解安全的PHP输出函数。
始终支持国际化 — 所有用户可见字符串必须使用主题/插件文本域包裹在翻译函数中。使用
```
esc_html_e()
```
（输出+转义+翻译）或
```
esc_html__()
```
（返回+转义+翻译）。请阅读
```
references/pattern-registration.md
```
了解文本域和国际化示例。
优先使用预设而非硬编码值 — 使用
```
"backgroundColor":"primary"
```
而非
```
"style":{"color":{"background":"#0073aa"}}
```
。预设可适配主题变更和样式变体。
合法嵌套 — 每个
```

```
必须有对应的
```

```
。嵌套顺序必须正确。自闭合区块使用
```

```
。
使用原生区块实现功能 — 使用查询循环、搜索、导航、社交图标或现有表单区块，而非自定义PHP/HTML功能。如需通讯、捐赠、支付或地图功能，请创建CTA/占位符或使用现有区块/插件；禁止自行编写表单、iframe、脚本或第三方处理逻辑。
优先使用本地资源 — 使用
```
get_theme_file_uri()
```
和
```
esc_url()
```
调用主题/插件资源。除非用户明确批准，否则避免使用外部占位图片URL。

参考：

references/block-markup-reference.md

了解语法，

references/anti-patterns.md

了解需避免的做法。

Procedure

操作流程

0) Triage and locate the pattern target

0) 分类定位模式目标

Run triage when working in a repository:

node skills/wp-project-triage/scripts/detect_wp_project.mjs

For block themes, locate the target theme root:

node skills/wp-block-themes/scripts/detect_block_themes.mjs

Confirm the pattern belongs in a theme
```
patterns/
```
directory or needs manual plugin registration.
If multiple themes/plugins exist, scope all changes to the requested target.

If the user did not provide required inputs, infer only low-risk defaults. Ask before inventing a theme slug, text domain, asset path, custom post type, taxonomy, event date field, or theme-specific preset. If

theme.json

is missing or presets cannot be verified, use conservative core presets or ask before using theme-specific slugs.

在代码库中运行分类检测：

node skills/wp-project-triage/scripts/detect_wp_project.mjs

对于区块主题，定位目标主题根目录：

node skills/wp-block-themes/scripts/detect_block_themes.mjs

确认模式应放在主题
```
patterns/
```
目录，还是需要手动插件注册
若存在多个主题/插件，确保所有修改仅限于请求的目标

如果用户未提供所需输入，仅推断低风险默认值。在创建主题标识、文本域、资源路径、自定义文章类型、分类法、事件日期字段或主题特定预设前，请先询问用户。如果

theme.json

缺失或无法验证预设，请使用保守的核心预设，或在使用主题特定标识前询问用户。

1) Design thinking

1) 设计思路

Before writing markup, make 5 deliberate design decisions. This is what separates distinctive patterns from generic AI output.

Reference:

references/design-with-tokens.md

for translating decisions to block attributes.

在编写标记前，做出5项明确的设计决策。这是区分独特模式与通用AI输出的关键。

参考：

references/design-with-tokens.md

了解如何将决策转化为区块属性。

Decision 1: Purpose

决策1：用途

What does this pattern achieve for the end user? A hero converts visitors. A testimonial grid builds trust. A pricing table drives comparison. Let purpose drive every subsequent choice.

该模式为终端用户实现什么目标？Hero区块转化访客， testimonial网格建立信任，定价表促进对比。让用途驱动后续所有选择。

Decision 2: Tone

决策2：风格

Choose a clear direction and map it to block attributes:

Tone	Color Strategy	Typography	Layout
Bold/energetic	High contrast, accent backgrounds, gradients	XX-large headings, tight letter-spacing, uppercase accents	Full-width, asymmetric columns, large padding
Minimal/refined	Base + contrast only, subtle tertiary sections	Restrained sizes, generous line-height	Constrained width, generous whitespace, centered
Editorial/magazine	Dark sections alternating with light	Mixed font families, varied heading scales	Asymmetric splits (66/33), media-text blocks
Playful/creative	Multiple accent colors, bright backgrounds	Large display sizes, varied weights	Grid layouts, unexpected column ratios, rounded corners
Corporate/professional	Neutral palette, primary for CTAs only	Consistent scale, body font dominant	Equal columns, structured grid, minimal decoration

选择清晰的方向并映射到区块属性：

风格	色彩策略	排版	布局
大胆/活力	高对比度、强调色背景、渐变	超大标题、紧凑字间距、大写强调	全屏、不对称列、大内边距
极简/精致	仅基础色+对比色、柔和的次要区块	克制的尺寸、宽松行高	受限宽度、充足留白、居中对齐
编辑/杂志	深色与浅色区块交替	混合字体族、多变标题层级	不对称分栏（66/33）、媒体文本区块
趣味/创意	多种强调色、明亮背景	大显示尺寸、多变字重	网格布局、意外列比例、圆角
企业/专业	中性调色板、仅CTA使用主色	统一层级、正文字体主导	等宽列、结构化网格、极简装饰

Decision 3: Spatial Composition

决策3：空间构图

Choose your primary layout strategy:

Constrained centered — classic content width with wide breakouts
Full-width sections — alternating background bands
Asymmetric split — 60/40 or 70/30 columns with content + media
Grid — block-native grid or columns layouts for cards, team members, portfolio items
Stacked vertical — flex column with varied spacing for editorial feel

Vary spacing intentionally:

Tight
```
blockGap
```
(spacing|20-30) for related elements within a card
Standard
```
blockGap
```
(spacing|40) for flowing content
Generous padding (spacing|60-80) on section wrappers for breathing room

选择主要布局策略：

居中受限 — 经典内容宽度搭配宽屏突破
全屏区块 — 交替背景色带
不对称分栏 — 60/40或70/30列搭配内容+媒体
网格 — 区块原生网格或列布局，适用于卡片、团队成员、作品集项目
垂直堆叠 — 弹性列搭配多变间距，营造编辑风格

有意调整间距：

卡片内相关元素使用紧凑
```
blockGap
```
（spacing|20-30）
流式内容使用标准
```
blockGap
```
（spacing|40）
区块包装器使用充足内边距（spacing|60-80）以预留呼吸空间

Decision 4: Typography Hierarchy

决策4：排版层级

Plan your type scale before writing markup:

Hero heading:

fontSize:"xx-large"

fontFamily:"heading"

+ tight

lineHeight

Section heading:
```
fontSize:"x-large"
```
+
```
fontFamily:"heading"
```

Subtitle/lead:

fontSize:"large"

textColor:"secondary"

fontFamily:"body"

Body:
```
fontSize:"medium"
```
or default
Caption/meta:
```
fontSize:"small"
```
+
```
textColor:"secondary"
```

Add at least one typographic accent:

Uppercase + letter-spacing for labels
Tight letter-spacing on display headings
Italic for pull quotes
Monospace for technical/code content

在编写标记前规划字体层级：

Hero标题：

fontSize:"xx-large"

fontFamily:"heading"

+ 紧凑

lineHeight

区块标题：
```
fontSize:"x-large"
```
+
```
fontFamily:"heading"
```

副标题/引导文本：

fontSize:"large"

textColor:"secondary"

或

fontFamily:"body"

正文：
```
fontSize:"medium"
```
或默认值
说明/元数据：
```
fontSize:"small"
```
+
```
textColor:"secondary"
```

添加至少一项排版强调：

标签使用大写+字间距
显示标题使用紧凑字间距
引用使用斜体
技术/代码内容使用等宽字体

Decision 5: Color Strategy

决策5：色彩策略

Plan section-by-section color flow:

Light section:
```
base
```
background,
```
contrast
```
text (default)
Dark section:
```
contrast
```
background,
```
base
```
text (inverted)
Accent section:
```
primary
```
or
```
tertiary
```
background
Gradient section: cover block with gradient overlay

A pattern with multiple sections should vary backgrounds — don't use the same background for every section.

逐区块规划色彩流程：

浅色区块：
```
base
```
背景色，
```
contrast
```
文本色（默认）
深色区块：
```
contrast
```
背景色，
```
base
```
文本色（反转）
强调区块：
```
primary
```
或
```
tertiary
```
背景色
渐变区块：使用渐变覆盖区块

包含多个区块的模式应更换背景色 — 切勿所有区块使用相同背景。

Pattern-specific decisions

模式特定决策

Starter pages: include
```
Block Types: core/post-content
```
unless the pattern is specifically for a template or template part.
Template patterns: set
```
Template Types
```
and use
```
Inserter: no
```
when the pattern should only be offered in template replacement flows.
Query Loop patterns: use
```
core/query
```
with
```
core/post-template
```
, post title/excerpt/date/featured image blocks, pagination, and
```
core/query-no-results
```
where relevant. For archive, search, category, and author templates, prefer inherited query context instead of custom PHP. For CPT/event queries, confirm the post type slug, taxonomy/date assumptions, and available blocks before generating markup.
Comparison, pricing, timeline, and schedule patterns: use clear headings, list/table or labeled-card structure, and non-color-only emphasis for featured states.
Social, navigation, and search patterns: use native blocks and verify accessible labels, link text, and search context. In 404 patterns, pair the Search block with recovery copy that explains what the user can try next.
Forms, donations, payments, maps, and newsletter signups: use an existing block/plugin/service or a static CTA/placeholder. Do not create raw form handling or third-party behavior inside a pattern.

起始页：除非模式专门用于模板或模板部件，否则需包含
```
Block Types: core/post-content
```
模板模式：设置
```
Template Types
```
，若模式仅应在模板替换流程中提供，需设置
```
Inserter: no
```
查询循环模式：使用
```
core/query
```
搭配
```
core/post-template
```
、文章标题/摘要/日期/特色图片区块、分页，以及相关的
```
core/query-no-results
```
。对于归档、搜索、分类和作者模板，优先使用继承的查询上下文而非自定义PHP。对于自定义文章类型/事件查询，在生成标记前确认文章类型标识、分类法/日期假设和可用区块。
对比、定价、时间线和日程模式：使用清晰标题、列表/表格或带标签的卡片结构，且强调特色状态时不依赖单一颜色。
社交、导航和搜索模式：使用原生区块并验证无障碍标签、链接文本和搜索上下文。在404模式中，将搜索区块与恢复文案配对，向用户说明后续可尝试的操作。
表单、捐赠、支付、地图和通讯注册：使用现有区块/插件/服务或静态CTA/占位符。禁止在模式内创建原始表单处理或第三方功能。

High-impact visual patterns

高影响力视觉模式

Use these composition moves when the request calls for a visually distinctive pattern:

Oversized display type: use a short word or title at display scale with tight line-height, uppercase or italic treatment, and enough surrounding space. Keep letter spacing at
```
0
```
unless the design specifically needs a tracked wordmark.
Offset color fields: split a cover background with a hard-stop gradient or two-tone color field, then let the type or image cross the boundary.
Editorial cover image: use a full-bleed Cover block with image, dim/duotone treatment, and left-anchored copy; place the CTA in a clearly separated lower area.
Image plus quiet content: use Media & Text for case-study or portfolio patterns where the image carries visual weight and the content side stays intentionally sparse.
Header plus hero: combine a flex header with Site Logo, Site Title, and Navigation above a full-width Cover when the pattern is a page opener or starter page.
Post index as graphic layout: for Query Loop patterns, make dates and titles part of the visual hierarchy with large title links, strong separators, and pagination.
Repeated display text: repeat a single word or short phrase in varied tones when the design is poster-like, but keep it readable and avoid repeating long content.
Centered image on two-tone field: place a single image inside a constrained group over a split-color background for a gallery, collection, or album-style pattern.

These moves should still pass the technical checklist: valid block markup, translatable/escaped strings, local or approved assets, accessible labels, no scripts, no inline

<style>

tags, and no custom CSS classes.

当请求需要视觉独特的模式时，可使用以下构图手法：

超大显示字体：使用短句或标题以显示尺寸呈现，搭配紧凑行高、大写或斜体处理，以及足够的周围留白。字间距保持为
```
0
```
，除非设计特别需要字距调整的文字标志。
偏移色彩区域：使用硬停止渐变或双色区域分割封面背景，让文字或图像跨越边界。
编辑风格封面图：使用全屏Cover区块搭配图片、暗化/双色调处理，以及左对齐文案；将CTA放在清晰分隔的下方区域。
图片+简洁内容：使用媒体与文本区块制作案例研究或作品集模式，让图片承载视觉重量，内容侧保持刻意简洁。
页眉+Hero：当模式为页面开场或起始页时，将包含站点Logo、站点标题和导航的弹性页眉与全屏Cover结合。
文章索引作为图形布局：对于查询循环模式，通过大标题链接、强分隔符和分页，让日期和标题成为视觉层级的一部分。
重复显示文本：当设计为海报风格时，重复单个单词或短句并使用不同风格，但需保持可读性，避免重复长内容。
双色背景上的居中图片：将单张图片放在约束组内，叠加在分色背景上，制作画廊、合集或专辑风格的模式。

这些手法仍需通过技术检查：合法区块标记、可翻译/转义字符串、本地或已批准资源、无障碍标签、无脚本、无内联

<style>

标签、无自定义CSS类。

2) Plan block structure

2) 规划区块结构

Sketch the nesting tree before writing markup. Example for a hero pattern:

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)

This step catches nesting errors and ensures intentional hierarchy before you write a single comment tag.

在编写标记前绘制嵌套树。Hero模式示例：

Group (全屏、受限布局、深色背景、垂直内边距80)
  Group (受限内部、垂直弹性、居中对齐)
    Paragraph (大写标签、小尺寸、字间距、强调色)
    Heading (h2、超大号、标题字体、紧凑行高)
    Paragraph (引导文本、大尺寸、次要颜色)
    Buttons (弹性、居中)
      Button (主色背景、基础文本色)
      Button (轮廓样式)

此步骤可提前发现嵌套错误，确保在编写任何注释标签前建立明确的层级。

3) Write the pattern file

3) 编写模式文件

Assemble the PHP header and block markup.

File header (for theme auto-registration):

php

<?php
/**
 * Title: [Descriptive Name]
 * Slug: theme-slug/pattern-name
 * Categories: [comma-separated slugs]
 * Keywords: [search terms]
 * Viewport Width: 1400
 * Block Types: [if starter/template part pattern]
 * Template Types: [if template pattern]
 */
?>

Reference:

references/pattern-registration.md

for all header fields and PHP rules. Reference:

references/pattern-categories-and-types.md

for category selection and template types.

For plugin or conditional patterns, register manually on

init

with

register_block_pattern()

. Use translated

title

description

, and

keywords

; keep

content

static block markup; and avoid runtime queries. Register custom categories before using them with

register_block_pattern_category()

or define theme-owned categories in

theme.json

. For WordPress versions before filesystem auto-registration support, use manual registration instead of

patterns/*.php

auto-discovery.

Block markup body:

Follow the nesting tree from step 3
Use preset slugs for colors, font sizes, spacing
Include
```
esc_html_e()
```
for all visible text
Include
```
esc_url( get_theme_file_uri() )
```
for theme images
Use placeholder text that reflects real content (not "Lorem ipsum" — use realistic example text appropriate to the pattern's purpose)

组装PHP头和区块标记。

文件头（适用于主题自动注册）：

php

<?php
/**
 * Title: [描述性名称]
 * Slug: theme-slug/pattern-name
 * Categories: [逗号分隔的标识]
 * Keywords: [搜索词]
 * Viewport Width: 1400
 * Block Types: [若为起始页/模板部件模式]
 * Template Types: [若为模板模式]
 */
?>

参考：

references/pattern-registration.md

了解所有头字段和PHP规则。参考：

references/pattern-categories-and-types.md

了解分类选择和模板类型。

对于插件或条件模式，在

init

阶段使用

register_block_pattern()

手动注册。使用已翻译的

title

、

description

和

keywords

；保持

content

为静态区块标记；避免运行时查询。在使用自定义分类前，需通过

register_block_pattern_category()

注册或在

theme.json

中定义主题所属分类。对于不支持文件系统自动注册的旧版WordPress，请使用手动注册而非

patterns/*.php

自动发现。

区块标记主体：

遵循步骤3的嵌套树
使用颜色、字体大小、间距的预设标识
所有可见文本使用
```
esc_html_e()
```
主题图片使用
```
esc_url( get_theme_file_uri() )
```
使用反映真实内容的占位文本（不要使用"Lorem ipsum"，使用与模式用途匹配的真实示例文本）

4) Design quality check

4) 设计质量检查

Review against anti-patterns (

references/anti-patterns.md

Not generic: pattern makes at least 3 distinctive design choices
Layout variety: not defaulting to 3 equal columns or uniform symmetric layouts
Color rhythm: sections alternate or vary backgrounds — not all the same
Typography contrast: headings clearly distinct from body (size, family, or weight)
Spatial intention: padding and gaps vary by context, not uniform everywhere
Meaningful content: placeholder text reflects real use, buttons describe actions
Specific structure: comparisons, timelines, schedules, pricing, menus, and documentation cards have labels that make sense without relying on visual position alone
Restrained but distinctive: corporate/professional patterns still include a clear hierarchy, accent, or layout choice; playful patterns do not become a one-note palette or repeated gradient treatment

对照反模式（

references/anti-patterns.md

）进行审核：

非通用化：模式至少做出3项独特设计决策
布局多样性：不默认使用3等列或统一对称布局
色彩节奏：区块交替或更换背景色 — 并非全部相同
排版对比度：标题与正文清晰区分（尺寸、字体族或字重）
空间意图：内边距和间距根据上下文变化，并非统一设置
有意义的内容：占位文本反映实际用途，按钮描述具体操作
特定结构：对比、时间线、日程、定价、菜单和文档卡片带有标签，无需依赖视觉位置即可理解
克制但独特：企业/专业模式仍包含清晰层级、强调元素或布局选择；趣味模式不会变成单一调色板或重复渐变效果

5) Technical validation

5) 技术验证

Every
```

```
has matching
```

```
JSON in block comments is valid (no trailing commas, strings double-quoted)
All user-visible strings use
```
esc_html_e()
```
or
```
esc_html__()
```
All URLs use
```
esc_url()
```
All attribute values with translatable text use
```
esc_attr_e()
```
or
```
esc_attr__()
```
Informational images have descriptive translated alt text; decorative images use empty alt text intentionally
Heading levels are sequential (h2 → h3 → h4, never skip)
Preset slugs are valid defaults or documented as theme-specific
```
Slug
```
in header uses correct namespace:
```
theme-slug/pattern-name
```
No inline
```
<style>
```
, no
```
<script>
```
, no custom CSS classes
No query-dependent PHP functions
Button/link labels are action-specific; avoid vague labels such as "Click Here" or "Read More"
Updating an existing pattern preserves the
```
Slug
```
unless intentionally creating a new pattern

每个
```

```
都有对应的
```

```
区块注释中的JSON合法（无尾随逗号、字符串使用双引号）
所有用户可见字符串使用
```
esc_html_e()
```
或
```
esc_html__()
```
所有URL使用
```
esc_url()
```
所有包含可翻译文本的属性值使用
```
esc_attr_e()
```
或
```
esc_attr__()
```
信息性图片包含描述性翻译替代文本；装饰性图片有意使用空替代文本
标题层级连续（h2 → h3 → h4，切勿跳过）
预设标识为合法默认值或已记录为主题特定
头中的
```
Slug
```
使用正确命名空间：
```
theme-slug/pattern-name
```
无内联
```
<style>
```
、无
```
<script>
```
、无自定义CSS类
无依赖查询的PHP函数
按钮/链接标签为特定操作；避免模糊标签如"点击此处"或"阅读更多"
更新现有模式时保留
```
Slug
```
，除非有意创建新模式

Verification

验证

Test the pattern in a real WordPress environment:

Using WordPress Playground (recommended):

bash

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

Mount the theme directory and verify:

Pattern appears in inserter under specified categories
Pattern inserts without block validation errors
Layout renders correctly at desktop and mobile widths
Content is editable (text, images, buttons)
If
```
templateLock
```
is used, locked elements resist editing

For template patterns, verify the Site Editor offers the pattern in the expected template replacement flow. If

Inserter: no

is used, confirm it is hidden from the general inserter but still available where intended.

Manual check:

Paste block markup into the Code Editor view in WordPress
Switch to Visual Editor — blocks should parse without "Attempt Block Recovery" prompts
If recovery is needed, the markup has syntax errors

Run the repo's existing lint, build, or test commands if the pattern change touches assets, generated files, or registration code.

When updating an existing pattern, remember that inserted pattern content is copied into posts/templates. Changing the pattern file does not retroactively update already inserted content, and changing block names or saved markup can create recovery prompts for newly inserted content.

For PR or package review, confirm the diff is scoped to the intended pattern files, references, scripts, and eval scenarios. Do not mix unrelated repo updates into a pattern change.

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

使用WordPress Playground（推荐）：

bash

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

挂载主题目录并验证：

模式在插入器中显示在指定分类下
模式插入时无区块验证错误
布局在桌面和移动宽度下正确渲染
内容可编辑（文本、图片、按钮）
若使用
```
templateLock
```
，锁定元素无法被编辑

对于模板模式，验证站点编辑器在预期的模板替换流程中提供该模式。若使用

Inserter: no

，确认它在通用插入器中隐藏，但在预期场景中仍可用。

手动检查：

将区块标记粘贴到WordPress的代码编辑器视图
切换到可视化编辑器 — 区块应正常解析，无"尝试区块恢复"提示
若需要恢复，说明标记存在语法错误

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

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

对于PR或包审核，确认差异仅限于预期的模式文件、参考资料、脚本和评估场景。请勿将无关的代码库更新混入模式变更中。

Failure modes / debugging

故障模式/调试

Start with

references/block-markup-reference.md

references/pattern-registration.md

, and

references/anti-patterns.md

Common failures:

Pattern missing from inserter: check required
```
Title
```
,
```
Slug
```
, and
```
Categories
```
headers; confirm the file is under
```
patterns/*.php
```
; confirm
```
Inserter: no
```
is not hiding it.
Wrong pattern shown or overwritten: check for slug collisions and ensure the slug is namespaced as
```
theme-slug/pattern-name
```
or
```
plugin-slug/pattern-name
```
.
Block recovery prompt appears: validate block comment nesting, JSON syntax, and closing comments.
Strings are not translated or escaped: replace raw text/PHP output with
```
esc_html_e()
```
,
```
esc_html__()
```
,
```
esc_attr_e()
```
,
```
esc_attr__()
```
, or
```
esc_url()
```
as appropriate.
Translations do not load: verify the text domain matches the target theme/plugin.
Dynamic content is stale or unavailable: remove query-dependent PHP (
```
get_posts()
```
,
```
the_title()
```
,
```
wp_get_current_user()
```
) and use blocks such as Query Loop instead.
Query Loop output is incomplete: check for
```
core/post-template
```
, post title/excerpt/date/image blocks, pagination when needed, and
```
core/query-no-results
```
fallback.
Archive/search/category/author context is wrong: use inherited query context instead of hardcoded runtime PHP.
CPT or event listings are wrong: confirm post type slugs, taxonomy/date fields, and plugin-provided blocks before generating the pattern.
Styles do not match the theme: confirm preset slugs exist in
```
theme.json
```
; avoid unsupported theme-specific slugs unless documented.
Accessibility issues: fix skipped heading levels, empty alt text for informational images, low-contrast preset combinations, vague button/link text, social icon labels, search labels, and color-only emphasis.
Manual registration fails: confirm the code runs on
```
init
```
, categories are registered before patterns, and pattern content remains static block markup.

首先参考

references/block-markup-reference.md

、

references/pattern-registration.md

和

references/anti-patterns.md

。

常见故障：

模式未出现在插入器中：检查必填的
```
Title
```
、
```
Slug
```
和
```
Categories
```
头；确认文件位于
```
patterns/*.php
```
下；确认未设置
```
Inserter: no
```
隐藏它。
显示错误模式或被覆盖：检查标识冲突，确保标识命名为
```
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。
自定义文章类型或事件列表错误：在生成模式前确认文章类型标识、分类法/日期字段和插件提供的区块。
样式与主题不匹配：确认预设标识在
```
theme.json
```
中存在；除非有文档记录，否则避免使用不支持的主题特定标识。
无障碍问题：修复跳过的标题层级、信息性图片的空替代文本、低对比度预设组合、模糊按钮/链接文本、社交图标标签、搜索标签和仅依赖颜色的强调。
手动注册失败：确认代码在
```
init
```
阶段运行，分类在模式前注册，且模式内容为静态区块标记。

Escalation

升级处理

Stop and ask for help or consult canonical docs when:

Theme-specific preset slugs, text domains, asset paths, or pattern categories cannot be verified.
Color contrast, image meaning, or content hierarchy needs human design/accessibility judgment.
Behavior depends on a WordPress/Gutenberg version that is not covered by this repo's compatibility contract.
The request requires a custom block, dynamic rendering, or saved-block migration; route to
```
wp-block-development
```
.
The request requires frontend interactivity beyond native blocks; route to
```
wp-interactivity-api
```
.

Use WordPress Developer Resources, the Theme Handbook, and the Block Editor Handbook for upstream behavior before inventing version-sensitive guidance.

出现以下情况时，请停止操作并寻求帮助或参考官方文档：

无法验证主题特定预设标识、文本域、资源路径或模式分类。
色彩对比度、图片含义或内容层级需要人工设计/无障碍判断。
功能依赖的WordPress/Gutenberg版本不在代码库兼容协议范围内。
请求需要自定义区块、动态渲染或已保存区块迁移；请转至
```
wp-block-development
```
技能。
请求需要超出原生区块的前端交互；请转至
```
wp-interactivity-api
```
技能。

在制定版本敏感的指导前，请先参考WordPress开发者资源、主题手册和区块编辑器手册的上游行为。

Example Prompts

示例请求

Hero Section

Hero区块

"Create a bold hero pattern with a large heading, subtitle, and two CTA buttons. Dark background, full-width, for a creative agency theme."

Expected: Cover or Group block with contrast bg, constrained inner, heading with xx-large + heading font, paragraph with secondary color, Buttons with primary + outline styles.

"为创意机构主题创建一个大胆的Hero模式，包含大标题、副标题和两个CTA按钮。深色背景，全屏显示。"

预期结果：使用对比色背景的Cover或Group区块，受限内部容器，超大号标题字体，次要颜色的段落文本，主色+轮廓样式的按钮组。

Testimonial Grid

Testimonial网格

"Create a 3-column testimonial grid with avatar, quote, name, and role. Alternating card backgrounds."

Expected: Group wrapper, block-native grid or Columns layout (3 columns, responsive), inner Group cards with varied tertiary/base backgrounds, Image block for avatar (rounded border-radius), Paragraph for quote (italic), Heading h3 for name, Paragraph small for role.

"创建一个3列的Testimonial网格，包含头像、引用、姓名和职位。交替卡片背景。"

预期结果：Group包装器，区块原生网格或列布局（3列，响应式），内部Group卡片使用不同的 tertiary/base背景色，头像使用Image区块（圆角边框），引用使用Paragraph区块（斜体），姓名使用h3标题，职位使用小尺寸Paragraph区块。

Blog Post Listing

博客文章列表

"Create a starter page pattern for a blog index with featured post hero and 3-column grid of recent posts below."

Expected:

Block Types: core/post-content

header, Query Loop for featured post (perPage 1, large layout), second Query Loop for grid (perPage 3, grid layout with post-template), clear visual separation between sections.

"创建一个博客索引的起始页模式，上方为特色文章Hero，下方为3列网格的最新文章。"

预期结果：头信息包含

Block Types: core/post-content

，特色文章使用查询循环（perPage 1，大布局），网格使用第二个查询循环（perPage 3，网格布局搭配post-template），区块间有清晰的视觉分隔。

Footer with Columns

列布局页脚

"Create a 4-column footer pattern with logo, navigation links, contact info, and social icons. Dark background."

Expected:

Block Types: core/template-part/footer

header, Group full-width with contrast bg, Columns (4), Site Logo block, Navigation or list blocks, Paragraph blocks for contact, Social Icons block.

Inserter: no

"创建一个4列页脚模式，包含Logo、导航链接、联系信息和社交图标。深色背景。"

预期结果：头信息包含

Block Types: core/template-part/footer

，全屏Group搭配对比色背景，4列布局，站点Logo区块，导航或列表区块，联系信息Paragraph区块，社交图标区块。设置

Inserter: no

。