miketropi/nextora-child-themes

Nextora 子佈景主題

建立與稽核 Nextora 的子佈景主題：引導程式、資產管線與子區塊註冊器。父系層級的慣例存在於父系本身；區塊內部細節屬於 ../nextora-gutenberg-blocks/SKILL.md，而關於調色盤、字型或訪客切換器的任何事項則屬於 ../nextora-design-system/SKILL.md。

需載入的參考文件

在撰寫任何檔案之前，請先閱讀以下相對路徑的檔案：

• references/child-contract.md — 包含 slug/前綴取代表、確切的目錄配方、標頭、引導與排隊程式碼、註冊器、PHP 慣例、範例中觀察到的缺陷以及下游 WordPress 接收配方。請在步驟 3 載入它，並且在擁有它之前不要撰寫任何程式碼。
• source-map.md — 每條規則的來源，包含出處標籤與常被誤述的事實。
• quality-gates.md — 用來衡量完成之子佈景主題的品質門檻。在宣告完成前載入它。

讀取本機原始碼的優先級高於讀取這些檔案。技能或參考文件中引用的每個值都只是一個錨點，而非當前事實。

有序工作流程

1. 解析根目錄，不要假設它們

在實際安裝環境中，父系是範本目錄，子系是樣式表目錄：

get_template_directory();      // parent root
get_stylesheet_directory();    // active theme root (child when one is active)

在安裝環境之外，找到一個 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、調色盤/字型 slug、customTemplates、templateParts。
4. package.json 與 .nvmrc — 存在哪些建置腳本，以及在哪個 Node 版本上。
5. inc/、blocks/、resources/、assets/ — 已存在哪些內容。

從父系中：style.css、functions.php、inc/assets/assets.php、blocks/blocks.php。這些是子系所依賴的，因此它們的 handle 名稱與註冊器行為才是契約，而非文件。

3. 在撰寫檔案之前先填入命名表格

載入 references/child-contract.md 並為請求的 slug 填入其取代表。每個產生的識別碼 — PHP 函式、常數、文字網域、區塊名稱、CSS 類別、自訂屬性、模式 slug、handle 以及檔案基礎名稱 — 都來自於那一個 slug。父系擁有的名稱（nextora_*、NEXTORA_*、nextora/*、global-styles、nextora-app、nextora-main、父系調色盤與字型 slug、--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 子系自己的檔案。每個依賴父系的操作都屬於一個鉤子內部，並且透過名稱引用父系的 handle，並先檢查它們是否已註冊。

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: 等於子系 slug，並且子系 PHP/JS 中的每個可翻譯字串都使用該網域。
• 在子系檔案範圍內沒有父系函式呼叫，也沒有讀取 NEXTORA_*。
• 每個排隊/編輯器樣式註冊都受到可讀檔案檢查的保護，並且在添加父系 handle 之前有 wp_style_is()/wp_script_is() 檢查。
• 子系資產基礎名稱不與父系的 app.css / main.js 衝突。
• 僅當 blocks/ 存在時區塊註冊器才存在，它使用樣式表目錄，跳過不可讀的 block.json，並註冊子系類別。
• 遵循了 references/child-contract.md 的結構，並套用了 quality-gates.md。
• 前端與編輯器畫布實際載入了子系資產。

邊界

此技能是 Markdown 指令。它不附帶任何產生器、起始佈景主題樹、套件管理器或安裝程式，並且它永遠不會編輯父系或範例子系。父系的 npm run gen 脚手架僅限於父系；子佈景主題是透過撰寫此處描述的檔案來建立的。