BIGboss248/nextjs-wordpress

Google Stitch UI 原型設計與變體技能 (stitch-design)

此技能定義了完整的流程，用於取得既定的元件設計規格文件 (design-spec.md)，並使用 Google Stitch (StitchMCP) 來搭建畫面佈局、生成空間變體、將高解析度視覺資產（JPG 截圖與原始 HTML 匯出）下載至程式碼庫中，以及使用具體的佈局基準來更新設計規格。

[!IMPORTANT] 輸入前置條件： 此技能需要一份已完成的設計規格文件，位於 docs/design/components/[page name]/[component name]/design-spec.md（通常由 component-design 產生）。若無此規格文件，請先執行 /component-design。

[!CAUTION] 二進位下載安全規則： 絕對不要使用 read_url_content 來下載 Stitch JPG 截圖或 HTML 匯出內容。read_url_content 僅供文字使用，且會將回應轉換為 markdown，這會導致二進位圖片損毀並破壞 HTML 結構。所有下載必須使用 run_command 搭配 PowerShell Invoke-WebRequest -Uri <url> -OutFile <path>。簽署的下載網址有效期限短——收到 Stitch 回應後請立即下載。

[!TIP] 技能內零圖片生成（代幣節約規則）： 為了節約代幣，此技能不得直接呼叫 generate_image。如果畫面需要自訂背景圖片、插圖或圖示，請制定並輸出結構化提示給使用者，讓他們自行生成並放置到專案檔案中。

---

1. 核心交付成果與流程概覽

flowchart TD
    Start["啟動 /stitch-design<br/>(目標：docs/design/components/[page]/[component]/design-spec.md)"] --> Step1["步驟 1：載入設計規格<br/>(讀取 design-spec.md 及 docs/project.json)"]
    Step1 --> Step2["步驟 2：Stitch 專案持久化與代碼種子設定<br/>(檢查/重複使用 docs/project.json 中的 stitch.project_id，植入設計系統)"]
    Step2 --> Step3["步驟 3：透過 StitchMCP 生成畫面及變體<br/>(generate_screen_from_text + 為 1 個變體執行 generate_variants)"]
    Step3 --> Step4["步驟 4：二進位安全資產下載<br/>(PowerShell Invoke-WebRequest → stitch/screen.jpg, screen.html, variant-1.jpg, variant-1.html)"]
    Step4 --> Step5["步驟 5：設計規格基準整合<br/>(將 stitch/screen.jpg 及變體基準嵌入 design-spec.md)"]
    Step5 --> Step6["步驟 6：獨立子代理驗證<br/>(invoke_subagent 驗證檔案大小、中繼資料及規格一致性)"]
    Step6 --> Finish["視覺原型準備就緒<br/>(Stitch JPG + HTML 已儲存於程式碼庫中)"]

交付項目：Stitch 資產子資料夾

每次執行 Stitch 都會在元件的設計目錄下建立或填充 stitch/ 子資料夾：

docs/design/components/[page name]/[component name]/
├── design-spec.md          # 已更新，包含 Stitch 基準及嵌入的截圖
└── stitch/                 # 已下載的 Google Stitch 設計檔案
    ├── screen.jpg          # Stitch 生成的主畫面 JPG 截圖
    ├── screen.html         # Stitch 生成的主畫面原始 HTML 匯出
    ├── variant-1.jpg       # Stitch 生成的變體 JPG 截圖
    ├── variant-1.html      # Stitch 生成的變體原始 HTML 匯出
    └── stitch-meta.json    # Stitch 專案 ID、畫面 ID、變體 ID 及生成提示

---

2. 逐步執行流程

步驟 1：載入設計規格與專案上下文

1. 定位目標元件：
   • 識別元件路徑：docs/design/components/[page name]/[component name]/。
   • 讀取 design-spec.md 以萃取：
     • 執行摘要、人物誌與情感基調。
     • 視覺層級（第一、第二及第三焦點）。
     • 佈局網格與斷點行為。
     • 設計代碼（顏色、圓角、高程）。
     • 各語言的字體配對。
2. 讀取專案上下文：
   • 讀取 docs/project.json 以驗證標準設計系統並檢查現有的 Stitch 設定。

---

步驟 2：Google Stitch 專案持久化與設計系統植入 (StitchMCP)

[!IMPORTANT] 每個儲存庫單一專案規則（零重複專案）： 每個儲存庫的所有元件與畫面設計，必須只維護一個共用的 Google Stitch 專案容器。絕對不要為同一個儲存庫建立多個 Stitch 專案。

1. 首先檢查 docs/project.json：
   • 檢查 docs/project.json 中是否存在包含 project_id 的 "stitch" 物件。
2. 重複使用現有專案：
   • 如果 stitch.project_id 存在，一律直接重複使用該 projectId 進行所有畫面搭建、變體及設計系統更新。請勿呼叫 create_project。
3. 建立並立即持久化（僅於缺失時）：
   • 如果 docs/project.json 中沒有 stitch.project_id：
     • 呼叫 call_mcp_tool 於 StitchMCP 上，使用 list_projects 檢查是否存在標題與儲存庫名稱相符的專案。
     • 如果沒有，則呼叫 create_project，設定 title: "[Project Title] Design System & Components"。
     • 立即將專案屬性持久化至 docs/project.json 中的 "stitch" 鍵下：

       "stitch": {
         "project_id": "<projectId>",
         "project_name": "projects/<projectId>",
         "title": "<title>"
       }
       

4. 植入設計代碼：
   • 透過 upload_design_md 或 create_design_system_from_design_md，將專案的標準設計系統（來自 docs/project.json）提供給 Stitch，以建立全域顏色、字體與圓角的一致性。

---

步驟 3：透過 StitchMCP 生成畫面與變體

1. 綜合詳細設計提示：
   • 結合來自 design-spec.md 的元件用途、使用者人物誌、情感基調及佈局需求。
   • 明確指定視覺代碼：來自 docs/project.json 的背景畫布、表面卡片、主要強調色、次要強調色、狀態顏色及字體。
   • 指定目標視埠：deviceType: "DESKTOP"（若針對行動優先元件則為 "MOBILE" / "TABLET"）。
2. 生成主畫面：
   • 呼叫 generate_screen_from_text 於 StitchMCP：
     • projectId：使用中的 Stitch 專案 ID。
     • prompt：綜合的設計提示。
     • deviceType："DESKTOP"。
   • 萃取生成的畫面 ID 與資源名稱（格式：projects/{projectId}/screens/{screenId}）。
3. 生成一個變體：
   • 對 StitchMCP 呼叫 generate_variants，使用生成的畫面 ID 來製作一個設計規格檔案的空間/視覺變體（例如探索替代的佈局密度、卡片式 vs. 滿版，或不對稱視覺流）。
   • 記錄變體畫面 ID。

---

步驟 4：二進位安全資產下載協定

[!CAUTION] 需要 PowerShell Invoke-WebRequest： 將每個下載命令作為離散的單一操作執行。驗證每個下載的檔案具有非零位元組大小（JPG 需大於 10KB）。

1. 確保目錄存在：
   • 目標目錄：docs/design/components/[page name]/[component name]/stitch/。
2. 下載主畫面 JPG：
   • 從主畫面回應中萃取 screenshot.downloadUrl。
   • 執行：

     powershell -Command "Invoke-WebRequest -Uri '<screenshot.downloadUrl>' -OutFile 'docs/design/components/[page]/[component]/stitch/screen.jpg'"
     

3. 下載主畫面 HTML：
   • 從主畫面回應中萃取 htmlCode.downloadUrl。
   • 執行：

     powershell -Command "Invoke-WebRequest -Uri '<htmlCode.downloadUrl>' -OutFile 'docs/design/components/[page]/[component]/stitch/screen.html'"
     

4. 下載變體 1 JPG：
   • 從變體回應中萃取 screenshot.downloadUrl。
   • 執行：

     powershell -Command "Invoke-WebRequest -Uri '<variant.screenshot.downloadUrl>' -OutFile 'docs/design/components/[page]/[component]/stitch/variant-1.jpg'"
     

5. 下載變體 1 HTML：
   • 從變體回應中萃取 htmlCode.downloadUrl。
   • 執行：

     powershell -Command "Invoke-WebRequest -Uri '<variant.htmlCode.downloadUrl>' -OutFile 'docs/design/components/[page]/[component]/stitch/variant-1.html'"
     

6. 儲存 Stitch 中繼資料 (stitch-meta.json)：
   • 寫入 docs/design/components/[page]/[component]/stitch/stitch-meta.json：

     {
       "projectId": "<stitchProjectId>",
       "screenId": "<screenId>",
       "screenName": "projects/<projectId>/screens/<screenId>",
       "deviceType": "DESKTOP",
       "generationPrompt": "<synthesizedPrompt>",
       "variantIds": ["<variantScreenId1>"]
     }
     

---

步驟 5：設計規格基準整合

使用 Stitch 結果更新 docs/design/components/[page name]/[component name]/design-spec.md：

1. 嵌入 Stitch 主畫面與變體：

   ## Google Stitch 佈局架構與基準
   
   ### 主畫面設計
   ![Primary Screen Design](stitch/screen.jpg)
   
   ### 變體 1 探索
   ![Variant 1 Design](stitch/variant-1.jpg)
   

2. 記錄佈局架構觀察：
   • 注意 Stitch 畫面中呈現的空間網格、視覺重量、留白節奏及字體層級。
   • 比較主畫面與變體 1，強調每種構圖的優勢。

---

步驟 6：視覺資產提示（如適用）

[!NOTE] 如果檢查 Stitch 佈局後發現需要客製的視覺資產（例如環境背景、自訂圖示或圖表），請不要呼叫 generate_image。請輸出結構化提示給使用者：

### 建議的視覺資產：[Asset Name]
- **目標檔案路徑：** `docs/design/components/[page]/[component]/[filename].png`
- **建議長寬比：** `16:9` 或 `1:1`
- **生成提示：**
  > "[詳細描述此視覺資產的提示，應與 Stitch 佈局相符]"

---

步驟 7：獨立子代理驗證迴圈 (invoke_subagent)

[!IMPORTANT] 子代理審查協定： 在報告完成之前，務必透過獨立的子代理驗證已下載的資產及規格更新。

1. 生成驗證子代理

呼叫 invoke_subagent，設定：

• TypeName："self"
• Role："Stitch Asset & Download Auditor"
• Model："inherit"
• Prompt：

You are an independent Stitch Asset Auditor. Your job is to verify that Google Stitch assets were downloaded cleanly and integrated into the component directory.

TARGET COMPONENT DIRECTORY:
docs/design/components/[page name]/[component name]/

Deliverables to Audit:
1. docs/design/components/[page name]/[component name]/stitch/screen.jpg (must exist, non-zero bytes)
2. docs/design/components/[page name]/[component name]/stitch/screen.html (must exist, raw HTML)
3. docs/design/components/[page name]/[component name]/stitch/variant-1.jpg (must exist, non-zero bytes)
4. docs/design/components/[page name]/[component name]/stitch/variant-1.html (must exist, raw HTML)
5. docs/design/components/[page name]/[component name]/stitch/stitch-meta.json (valid JSON with projectId, screenId, generationPrompt, variantIds)
6. docs/design/components/[page name]/[component name]/design-spec.md (must embed stitch/screen.jpg and stitch/variant-1.jpg)

Audit against these strict criteria:
1. Binary File Integrity: Confirm screen.jpg and variant-1.jpg are not empty or corrupted (size > 10KB).
2. HTML Integrity: Confirm screen.html and variant-1.html are valid HTML files and not corrupted markdown.
3. Metadata Integrity: Confirm stitch-meta.json has valid fields.
4. Spec Integration: Confirm design-spec.md contains the embedded screenshot links and Stitch layout benchmark notes.
5. Token Conservation: Confirm generate_image was NOT called directly.

Respond in this exact format:
VERDICT: PASS | ISSUES_FOUND

ISSUES (if any):
- LOCATION: {file:line or section}
- PROBLEM: {what is non-compliant or broken}
- FIX: {concrete instruction to fix}

SUMMARY: {brief overall evaluation}

2. 評估審查並解決問題

如果發現 ISSUES_FOUND，請立即解決（例如重新下載失敗的資產或修正中繼資料），然後再完成執行。

---

3. 執行驗證檢查清單

在完成執行之前，請驗證：

• 已從 docs/design/components/[page]/[component]/ 載入 design-spec.md。
• 已從 docs/project.json 驗證/重複使用 Stitch 專案 ID（或已建立並立即持久化）。
• 已透過 upload_design_md 或 create_design_system_from_design_md 將設計代碼植入 Stitch。
• 已透過 generate_screen_from_text 生成主畫面。
• 已透過 generate_variants 生成剛好一個變體。
• 所有資產都已使用 PowerShell Invoke-WebRequest -OutFile 下載（未使用 read_url_content）。
• screen.jpg、screen.html、variant-1.jpg、variant-1.html 已儲存在 stitch/ 中且大小非零。
• stitch/stitch-meta.json 已儲存並包含完整的中繼資料。
• design-spec.md 已更新，包含嵌入的截圖及 Stitch 佈局基準。
• 未直接呼叫 generate_image；若需要，已為使用者輸出圖片提示。
• 已透過 invoke_subagent 啟動獨立子代理審計且已通過。