wp-block-themes

WP 區塊佈景主題

使用時機

當進行區塊佈景主題相關工作時使用此技能，例如：

• 編輯 theme.json（預設值、設定、樣式、區塊專屬樣式）
• 新增或修改範本（templates/*.html）與範本部件（parts/*.html）
• 新增版型（patterns/*.php）並控制插入器中顯示的內容
• 新增樣式變化（styles/*.json）
• 除錯「樣式未套用」/「編輯器未反映 theme.json」

必要輸入

• 儲存庫根目錄以及目標佈景主題（若有多個佈景主題，需指定目錄）。
• 目標 WordPress 版本範圍（theme.json 版本與功能會隨核心版本而異）。
• 問題發生的位置：網站編輯器、文章編輯器、前台，或全部。

操作程序

0) 分類並定位區塊佈景主題根目錄

1. 執行分類：
   • node skills/wp-project-triage/scripts/detect_wp_project.mjs
2. 偵測佈景主題根目錄與關鍵資料夾：
   • node skills/wp-block-themes/scripts/detect_block_themes.mjs

若存在多個佈景主題，請選取一個，並將所有變更限定於該佈景主題根目錄。

1) 建立新的區塊佈景主題（如有需要）

若您從頭建立新的區塊佈景主題（或轉換傳統佈景主題）：

• 建議從已知良好的骨架開始（或從 WP 環境匯出），而非猜測檔案結構。
• 明確指定最低支援的 WordPress 版本，因為 theme.json 的結構版本會有所不同。

閱讀：

• references/creating-new-block-theme.md

建立佈景主題根目錄後，重新執行 detect_block_themes，並繼續以下步驟。

2) 確認佈景主題類型與覆寫預期

• 區塊佈景主題的標誌：
  • 存在 theme.json
  • 存在 templates/ 和/或 parts/
• 記住樣式階層：
  • 核心預設值 → theme.json → 子佈景主題 → 使用者自訂
  • 使用者自訂可能導致 theme.json 的編輯看起來「被忽略」

閱讀：

• references/debugging.md（樣式階層 + 快速檢查）

3) 安全地修改 theme.json

判斷您要修改的是：

• settings（UI 允許的項目）：預設值、字型尺寸、顏色、版面、間距
• styles（預設外觀）：元素/區塊的 CSS 規則

閱讀：

• references/theme-json.md

4) 範本與範本部件

• 範本位於 templates/ 下，為 HTML 格式。
• 範本部件位於 parts/ 下，且不得巢狀於子目錄中。

閱讀：

• references/templates-and-parts.md

5) 版型

當您需要佈景主題自有的版型時，建議使用 patterns/ 下的檔案系統版型。

閱讀：

• references/patterns.md

6) 樣式變化

樣式變化是 styles/ 下的 JSON 檔案。請注意：一旦使用者選取了某個樣式變化，該選擇會儲存在資料庫中，因此修改檔案可能不會自動「更新使用者看到的內容」。

閱讀：

• references/style-variations.md

驗證

• 網站編輯器在預期位置反映變更（樣式 UI、範本、版型）。
• 前台呈現預期樣式。
• 若樣式未改變，請確認使用者自訂是否覆寫了佈景主題預設值。
• 若有資產（字型、自訂 JS/CSS 建置），請執行儲存庫的建置/語法檢查腳本。

失敗模式 / 除錯

從以下開始：

• references/debugging.md

常見問題：

• 錯誤的佈景主題根目錄（編輯到未啟用的佈景主題）
• 使用者自訂覆寫了您的預設值
• 無效的 theme.json 結構/拼寫錯誤導致無法套用
• 範本/部件放在錯誤的資料夾（或部件巢狀化）

升級處理

若上游行為不明確，請查閱官方文件：

• 佈景主題手冊與區塊編輯器手冊，關於 theme.json、範本、版型與樣式變化。