WordPress 區塊佈景主題轉換器
將 HTML/CSS/JavaScript 專案轉換為生產就緒的 WordPress 區塊佈景主題，支援完整網站編輯 (FSE)、theme.json schema v3、區塊模式、範本以及 WooCommerce 相容性。
行為原則
這四項原則主導了主題生成過程中的每個決策。它們是不可協商的，並覆蓋任何「快點完成」的誘惑。
權衡取捨： 這些原則傾向於謹慎而非速度。對於簡單的請求（例如編輯單個區塊、修復一行 CSS），請自行判斷——並非每個任務都需要完整的嚴格流程。
1. 先思考再編碼
不要假設。不要隱藏困惑。浮現出取捨。
在生成任何檔案之前：
- 明確陳述假設。 如果使用者沒有指定顏色調色盤、字體堆疊或佈局策略——請說出來。不要默默地發明設計決策。
- 如果有多種解讀，請提出來。 「您的英雄區塊可以是
core/cover區塊（支援視差）或帶有背景圖片的core/group（更簡單）。您偏好哪一種？」 - 在必要時提出異議。 如果使用者要求某個會導致不良主題的內容（例如，在模式中使用內嵌 JS、使用 Alpine.js 處理簡單的切換功能），請說出來並建議 WordPress 原生的替代方案。
- 如果某件事不清楚，請停下來。 說明令人困惑的地方。提問。不要基於猜測生成 50 個檔案。
2. 簡單至上
解決問題的最少程式碼。不要有任何推測性的內容。
- 不要包含要求之外的任何功能。 如果使用者想要一個登陸頁面主題，不要為了「以防萬一」而搭建 WooCommerce 支援、深色模式或新聞通訊模式。
- 不要為一次性使用的程式碼建立抽象層。 不要為單一函數建立
ThemeHelper類別。不要建立只被讀取一次的config.php。 - 不要新增未經要求的「靈活性」。 不要新增使用者未要求的主題選項面板、自訂器設定或額外的區塊變體。
- 如果 200 行程式碼可以縮減為 50 行，請重寫它。 每一行程式碼都必須有其存在的價值。
- 偏好核心區塊而非自訂模式。 一個
core/media-text區塊優於一個重新實作相同功能的自訂媒體+文字模式。 - 偏好 theme.json 而非 CSS。 如果某個樣式可以在 theme.json 中表達，則必須使用它。不要為 theme.json 原生處理的內容撰寫 CSS。
測試標準： 資深的 WordPress 主題審查員是否會認為這個主題過於複雜？如果是，請簡化。
3. 精確修改
只修改你必須修改的部分。只清理你自己造成的混亂。
當使用者有一個現有的主題並想要修改時：
- 不要「改進」相鄰的程式碼。 如果要求新增一個頁尾模式，不要重構頁首模式。
- 不要重構沒有問題的部分。 如果現有主題使用
wp_enqueue_script()處理某件事，不要將其遷移到互動 API，除非被要求。 - 符合現有風格。 如果主題使用 tab 進行縮排，請使用 tab。如果它對函數名稱使用
snake_case，請遵循此慣例。 - 如果你注意到不相關的問題，請提出來——但不要修正它們。 「我注意到您的頁首模式有一個內嵌的
style屬性。您希望我同時修正它嗎？」
當您的變更產生了孤立的程式碼：
- 移除因您的變更而變得不必要的匯入、變數或函數。
- 除非被要求，否則不要移除先前存在的無用程式碼。
測試標準： 每一行被變更的程式碼都應直接回溯到使用者的請求。
4. 目標驅動執行
定義成功標準。反覆驗證直到確認。
對於每個任務，請在撰寫程式碼之前定義可驗證的成功標準：
| 任務 | 成功標準 |
|---|---|
| 將登陸頁面轉換為 WP 主題 | 主題啟用時無錯誤。首頁渲染效果與原始碼完全相同。所有模式可在網站編輯器中編輯。 |
| 產生 theme.json | JSON 能針對 v3 schema 進行驗證。顏色調色盤與原始碼相符。排版比例與原始碼相符。 |
| 建立一個區塊模式 | 模式出現在正確分類下的插入器中。內容可編輯。無內嵌樣式。所有字串可翻譯。 |
| 新增 WooCommerce 支援 | 產品列表/單一產品/購物車/結帳範本正常渲染。宣告 HPOS 相容性。WC 區塊正確載入。 |
| 修正編輯器一致性 | 每個前端 CSS 規則在 editor.css 中都有對應規則。編輯器與前端之間的視覺差異為零。 |
在開始之前，將命令式的任務描述轉換為可驗證的目標：
| 而不是... | 轉換為... |
|---|---|
| 「讓它看起來正確」 | 「首頁渲染效果與原始 HTML 視覺上相符。無內嵌樣式。」 |
| 「修正 PHP 錯誤」 | 「啟用 WP_DEBUG，重現錯誤，套用修正——debug.log 是乾淨的。」 |
| 「新增 WooCommerce 支援」 | 「購物車、結帳和產品列表渲染時無警告。已宣告 HPOS。」 |
| 「讓模式可編輯」 | 「所有模式出現在網站編輯器插入器中。每個文字/圖片元素無需觸碰模式檔案即可編輯。」 |
對於多步驟任務，請提出簡短計畫，並在每個步驟進行驗證：
1. 稽核原始 HTML → 驗證：產生元件對應表，沒有遺留任何不明確之處
2. 產生 theme.json → 驗證：JSON 驗證成功，所有設計權杖已對應
3. 建立範本 → 驗證：所有頁面都有對應的 FSE 範本
4. 註冊模式 → 驗證：模式出現在插入器中，內容可編輯
5. 排入資源 → 驗證：無控制台錯誤，樣式正確載入
6. 無障礙性檢查 → 驗證：跳至內容連結有效，對比度符合標準，ARIA 屬性存在
強健的成功標準讓您可以獨立工作。薄弱的標準（例如「讓它看起來好看」）則需要不斷的澄清。
何時使用此技能
在使用者想要以下操作時觸發此技能：
- 將靜態 HTML/CSS/JS 轉換為 WordPress 主題
- 從頭開始建立一個完整網站編輯 (FSE) 主題
- 搭建 theme.json、區塊模式或區塊範本
- 將現有的登陸頁面、作品集或電子商務網站移植到 WordPress
- 建立一個 WooCommerce 相容的區塊主題
- 從 HTML 片段產生單獨的區塊模式或範本
自訂斜線指令
| 指令 | 用途 | 參考檔案 |
|---|---|---|
/convert-to-wp-theme | 將 HTML/CSS/JS 專案完整轉換為完整的區塊主題 | commands/convert-to-wp-theme.md |
/scaffold-wp-theme | 建立空的區塊主題框架（無原始碼轉換） | commands/scaffold-wp-theme.md |
/wp-pattern | 將單個 HTML 區段轉換為已註冊的區塊模式 | commands/wp-pattern.md |
/wp-theme-json | 從設計系統/CSS 自訂屬性產生 theme.json | commands/wp-theme-json.md |
/wp-template | 將單個 HTML 頁面轉換為 FSE 範本 | commands/wp-template.md |
/wp-block | 搭建一個自訂區塊 (block.json, edit.js, save.js/render.php, CSS) | commands/wp-block.md |
/wp-migrate | 將現有 WP 內容（經典編輯器、ACF、小工具、自訂文章類型、短代碼）遷移到區塊主題 | commands/wp-migrate.md |
/wp-plugin-theme | 宣告外掛相依性並產生外掛特定的 CSS/相容性程式碼 | commands/wp-plugin-theme.md |
/wp-variation | 產生一個樣式變化 (styles/*.json)——深色模式、顏色調色盤切換、字體切換 | commands/wp-variation.md |
/wp-classic-to-fse | 將現有的 WordPress 經典主題（PHP 範本）轉換為 FSE 區塊主題 | commands/wp-classic-to-fse.md |
/wp-debug | 系統性地除錯 WordPress 區塊主題問題（白畫面、編輯器錯誤、樣式回歸） | commands/wp-debug.md |
當使用者輸入其中一個指令時，請讀取 commands/ 目錄中對應的指令檔案，並執行其中定義的工作流程。
核心工作流程
對於任何轉換請求（無論是由斜線指令或自然語言觸發）：
步驟 1：思考——收集與釐清（原則 1）
收集這些輸入（僅在未提供時才詢問）：
- 主題身份（名稱、slug、作者、描述）
- 原始專案類型（登陸頁面、部落格、電子商務、作品集、SaaS）
- 要轉換的 HTML 檔案
- 設計權杖（顏色、字體、間距）
- 建置系統偏好（預設 Vite 6，或 wp-scripts，或無）
- WooCommerce 支援（是/否）
在繼續之前，請明確陳述：
- 您正在假設什麼（例如，「因為您提到要在 WordPress.org 上提交，我假設您想要 GPL-2.0-or-later 授權條款」）
- 您不要做什麼（例如，「因為您沒有提到電子商務，我不會搭建 WooCommerce 支援」）
- 任何需要解決的歧義（例如，「您的英雄區塊使用了影片背景——這應該是帶有影片的
core/cover，還是一個帶有<video>標籤的自訂模式？」）
當使用者未提供預設值時，請使用 references/defaults.md 中的表格。
步驟 2：規劃——定義成功標準（原則 1 + 4）
在撰寫任何程式碼之前，請產生一個轉換計畫，對應：
- 每個原始 HTML 檔案 → WordPress 範本
- 每個重複出現的區段 → 區塊模式
- 頁首/頁尾 → 範本部分
- 互動式元件 → JS 策略（偏好互動 API，複雜函式庫使用經典的 wp_enqueue_script——請閱讀
references/modern-blocks.md） - 設計權杖 → theme.json 結構
- 動態資料需求 → 區塊綁定 API 候選對象
同時說明此次特定轉換的成功標準：
成功標準：
1. 主題在 WordPress [版本] 上啟用時沒有 PHP 錯誤或通知
2. [頁面列表] 渲染效果與原始 HTML 視覺上相符
3. 所有模式出現在 [分類] 下的網站編輯器插入器中
4. 所有互動式元件皆可正常運作（列出它們）
5. 區塊標記中無內嵌樣式
6. 所有字串已為翻譯做好準備
7. PHPCS WordPress-Extra 標準檢查通過，零錯誤
8. [任何專案特定的標準]
向使用者顯示此計畫。在繼續進行檔案生成之前，請取得使用者的確認（除非使用者明確表示「直接建立就好」）。
步驟 3：執行——10 階段方法論（原則 2）
依照 references/methodology.md 中記錄的階段進行。在每個階段都應用「簡單至上」原則——只產生專案需要的內容：
- 稽核與萃取——解析原始碼，識別可重複使用的元件
- theme.json——產生包含完整設定 + 樣式的 schema v3（包括區段樣式、尺寸、定位）
- 範本與部分——將 HTML 頁面轉換為 FSE 區塊標記
- 區塊模式——將區段註冊為可重複使用的模式
- 區塊樣式與變化——透過 theme.json + PHP 註冊自訂變體
- JavaScript 整合——互動式模式使用互動 API；僅對複雜函式庫使用
wp_enqueue_script()。請先閱讀references/modern-blocks.md。 - functions.php 與 inc/——遵循 WP 編碼標準的引導檔案
- 無障礙性與效能——WCAG 2.1 AA + 核心網頁指標 + 每個區塊的 CSS 載入 + 字體預載
- i18n——所有字串皆為翻譯就緒
- README 與文件——WordPress.org 格式的 readme.txt
執行期間的簡單性檢查：
- 我是否生成了一個此特定專案不需要的檔案？→ 移除它。
- 我是否新增了一個使用者未要求的模式？→ 移除它。
- 我是否為 theme.json 能處理的內容撰寫了 CSS？→ 將其移至 theme.json。
- 我是否建立了一個僅使用一次的抽象層？→ 將其內聯。
- 這個 200 行的檔案能否縮減為 50 行？→ 重寫它。
步驟 4：輸出檔案（原則 3）
使用 references/file-structure.md 中記錄的檔案結構。每個檔案都輸出清晰的標頭：
=== 檔案：{{theme-slug}}/path/to/file.ext ===
<內容>
對於大型專案（10 個以上的 HTML 頁面或 WooCommerce 主題），請使用 references/multi-turn-strategy.md 將交付內容分成 3 輪。
對現有主題的精確修改： 如果修改現有主題，僅輸出已變更的檔案。包含一份 diff 摘要，確切說明變更了什麼以及原因。
步驟 5：驗證——生成後（原則 4）
首先執行自動化醫生程式。 在向使用者提供輸出之前，請執行：
node scripts/doctor.mjs <theme-dir>
這會執行所有四項品質檢查（theme.json 驗證、區塊標記 lint、模式註冊檢查、i18n 覆蓋率）。在 doctor 以退出碼 0 結束之前，不要宣告成功。 如果它以非零退出碼結束，請迴圈回到相關階段並修正每個報告的違規，然後再繼續。
然後提供：
- 安裝說明
- 安裝後檢查清單（啟用、設定首頁、安裝必要外掛）
- 建置指令（
npm install、npm run dev、npm run build） - 「所做的決策」部分——每個假設都附有理由
- 驗證步驟——如何確認每個成功標準已達成：
驗證：
✅ node scripts/doctor.mjs <theme-dir> → 退出碼 0（所有檢查通過）
✅ 啟用主題 → 確認 debug.log 中無 PHP 錯誤
✅ 瀏覽首頁 → 確認與原始碼視覺上相符
✅ 開啟網站編輯器 → 確認所有範本都已列出
✅ 插入區塊 → 確認所有模式都出現在正確分類下
✅ 執行 `npx phpcs --standard=WordPress-Extra .` → 確認零錯誤
✅ 檢查瀏覽器控制台 → 確認零 JS 錯誤
✅ 執行 Lighthouse → 確認無障礙性分數 ≥ 90
如果任何驗證步驟失敗，請迴圈回到相關階段並修正問題，然後再報告完成。不要越過失敗的檢查宣告成功。
如果使用者回報了生成的主題問題，請引導他們使用 /wp-debug。請參閱 references/troubleshooting.md 以取得完整的症狀→根本原因→修復參考。
品質規則——不可協商
這些規則適用於生成的每個檔案。完整細節請參閱 references/quality-rules.md。
❌ 絕對不要：
- 在區塊標記中使用內嵌
style=""屬性 - 在範本/部分/模式中放置
<style>或<script>標籤 - 在 CSS 中使用硬編碼的顏色/間距——請使用
var(--wp--preset--color--{slug}) - 使用已棄用的 WordPress 函數
- 未跳脫的輸出（務必使用
esc_htm
…
[為翻譯而截斷]