miketropi/nextora-child-themes

Nextora 子主题

创建和审计 Nextora 的子主题：引导、资产管道和子块注册器。父级约定位于父主题本身；块内部属于 ../nextora-gutenberg-blocks/SKILL.md；关于调色板、字体或访客切换器的任何内容属于 ../nextora-design-system/SKILL.md。

需要加载的参考文件

在编写任何文件之前，请通过相对路径阅读以下文件：

• references/child-contract.md — 别名/前缀替换表、精确目录配方、头部、引导和入队代码、注册器、PHP 约定、示例中观察到的缺陷以及下游 WordPress 验收配方。在步骤 3 加载它，并在加载之前不要编写代码。
• source-map.md — 每条规则的来源，带有出处标签和常被误述的事实。
• quality-gates.md — 用于衡量完成子主题的质量门。在宣告完成之前加载它。

阅读本地源代码比阅读这些文件更重要。技能或参考文件中引用的每个值都是锚点，而非当前事实。

有序工作流程

1. 解析根目录，不要假设它们

在实时安装中，父主题是模板目录，子主题是样式表目录：

get_template_directory();      // 父主题根目录
get_stylesheet_directory();    // 活动主题根目录（当子主题活动时则为子主题根目录）

在安装环境之外，找到带有 Theme Name: Nextora 的 style.css 作为父主题，以及带有 Template: nextora 的 style.css 作为子主题。如果父主题源确实缺失，请说明并停止声明 Nextora 兼容性；仅完成不依赖父主题的工作。切勿编造锚点，也切勿静默地替换为另一个不同主题。

2. 在提出任何建议之前先审查证据

从目标子主题——或者当正在移植示例子主题时，从示例子主题：

1. style.css — 真实头部：Template、Version、Requires at least、Requires PHP、Tested up to、Text Domain、License。
2. functions.php — 加载顺序以及主题在文件作用域要求的内容。
3. theme.json — version、调色板/字体别名、customTemplates、templateParts。
4. package.json 和 .nvmrc — 存在哪些构建脚本，以及基于哪个 Node 版本。
5. inc/、blocks/、resources/、assets/ — 已存在哪些内容。

从父主题：style.css、functions.php、inc/assets/assets.php、blocks/blocks.php。这些是子主题依赖的内容，因此它们的句柄名称和注册器行为是约定，而非文档。

3. 在编写文件之前修复命名表

加载 references/child-contract.md 并为其请求的别名填充替换表。每个生成的标识符——PHP 函数、常量、文本域、块名称、CSS 类、自定义属性、模式别名、句柄和文件基名——都来自同一个别名。父主题拥有的名称（nextora_*、NEXTORA_*、nextora/*、global-styles、nextora-app、nextora-main、父主题调色板和字体别名、--nextora-font-* 角色）永远不会被重命名。

4. 仅布局子主题需要的目录

配方在 references/child-contract.md 中。必需：根目录下的 style.css、theme.json、functions.php。根据需要添加 inc/、resources/、assets/、templates/、parts/、patterns/，仅当子主题实际提供自定义块时才添加 blocks/<block-slug>/，并且仅当提供字体时才添加字体及其许可证文件。不要创建空白的功能脚手架，也不要克隆整个主题树。

5. 编写头部，然后是版本常量，最后是引导

顺序很重要：inc/bootstrap/version.php 定义了唯一的 <CHILD_PREFIX>_VERSION 常量，style.css 头部中的 Version: 必须与之相等，并且资产管道会回退到它，因此常量必须存在于任何需要管道的内容之前。在头部中，只声明真实的最低要求——切勿复制另一个主题的 Tested up to 值。

6. 编写遵循“子在前”原则的 functions.php

WordPress 在父主题的 functions.php 之前加载子主题的 functions.php，因此文件作用域中不得调用父函数或读取 NEXTORA_* 常量。从样式表目录定义子主题自己的 _DIR/_URI，仅当 Composer 自动加载器可读时才 require 它，并 require 子主题自己的文件。每个依赖父操作的操作都必须在钩子内部进行，通过名称引用父句柄，并在添加之前检查它们是否已注册。

7. 连接资产管道

子主题样式表在 wp_enqueue_scripts 优先级 25 上，当父主题的 global-styles 和 nextora-app 已注册时依赖它们；子主题脚本在优先级 30 上，当 nextora-main 已注册时依赖它；编辑器画布样式在 after_setup_theme 优先级 20 上通过 add_editor_style() 添加。每个入队都需通过可读文件检查进行保护，并使用不冲突的输出基名——子主题的 assets/css/app.css 或 assets/js/main.js 可能会遮蔽父主题的资产。完整代码和钩子表：references/child-contract.md。

8. 仅当子主题提供块时才添加块注册器

WordPress 不会扫描主题的 blocks/ 文件夹。在 init 上从 get_stylesheet_directory() 注册每个包含可读 block.json 的目录，添加子主题插入器类别，并在客户端镜像类别强制转换。块元数据、编辑器 UI 和渲染器属于 ../nextora-gutenberg-blocks/SKILL.md。没有 blocks/ 目录意味着没有注册器要求。

9. 将外观交给设计系统

如果子主题必须遵循预设或访客颜色/字体切换，请在同一会话中加载 ../nextora-design-system/SKILL.md，让它决定角色绑定、theme.json 字体系列和预设文件。子主题的正文、标题和按钮通过 Nextora 角色变量解析；它们永远不会直接固定到一个示例设计的字体上。

10. 针对运行中的站点进行验证

仅运行目标子主题自己的 package.json 声明的构建命令，然后加载一个前端页面和编辑器画布，确认资产确实已入队，并且保护措施没有隐藏缺失的构建。references/child-contract.md 中的验收配方是浏览器级别的证明。将任何你未实际操作的内容标记为未验证。

完成检查项

• 父主题和子主题从其自己的 style.css 解析，而非假定或硬编码。
• Template: nextora 存在；头部 Version 等于 <CHILD_PREFIX>_VERSION。
• Text Domain: 等于子主题别名，并且子主题 PHP/JS 中的每个可翻译字符串都使用该域。
• 在子主题文件作用域中没有父函数调用且没有 NEXTORA_* 读取。
• 每个入队/编辑器样式注册都通过可读文件检查和 wp_style_is()/wp_script_is() 检查进行保护，然后才添加父句柄。
• 子主题资产基名不与父主题的 app.css / main.js 冲突。
• 仅当 blocks/ 目录存在时才存在块注册器，使用样式表目录，跳过不可读的 block.json，并注册子主题类别。
• 遵循 references/child-contract.md 的结构，并应用 quality-gates.md。
• 前端和编辑器画布实际加载子主题资产。

边界

此技能是 Markdown 指令。它不提供生成器、起始主题树、包管理器或安装程序，并且从不编辑父主题或示例子主题。父主题的 npm run gen 脚手架仅适用于父主题；子主题是通过编写此处描述的文件创建的。