前言

最近，draw.io MCP 被公開。
結合這個與 Playwright MCP，

• 轉到畫面並獲取螢幕截圖（Playwright）
• 生成包含項號的佈局圖（draw.io）
• 根據 HTML/圖片撰寫 Markdown 的 畫面設計書 （Copilot）

……感覺可以相當自動化，因此在假日時試了一下，留下這篇筆記。

先說結論

• 在已經有現有設計書的情況下，為了維護目的“更新”來說還為時尚早（特別是“項號一致性”不穩定）
• 在沒有畫面設計書（幾乎沒有）的專案中，從 0 → 1 的創造用途 看起來還蠻實用的

所有提示與技能後文會詳述。
若有“這樣做會更好”的改善建議，期待收到您的評論。

前提

• IDE：VS Code（使用 GitHub Copilot Chat）
• 模型：Claude Opus 4.5
• Node（可使用 npx）
• 操作系統：Windows（包含 PowerShell 為前提的步驟）
• 畫面設計書中最低限度需要包含的項目
  • 佈局圖（全螢幕截圖）
  • 畫面項目的列表
  • 操作事件的列表

本地 MCP 伺服器可以在本地執行任意程式碼，因此前提是只能使用可信的內容。
此外，處理 .env 的憑證時，請 禁止錯誤提交（.gitignore），並在共享時需小心處理。

如何讓它自動化？

基本方針如下：

1. 使用 Playwright 操作應用程式（登錄 → 轉到目標畫面 → 獲取截圖）
2. 使用 draw.io 將全螢幕截圖作為底圖生成帶有項號的佈局圖（PNG + drawio）
3. 根據佈局圖 + 畫面 HTML 生成符合模板的畫面設計書（Markdown）

準備項目

準備的文件大致分為兩類。

1. 進行 MCP 設定的 mcp.json
2. Copilot 在執行任務時讀取的 SKILL.md（Agent Skills）

1. .vscode/mcp.json

在 .vscode/mcp.json 中，列出此次使用的 draw.io MCP 和 Playwright MCP。

{
  "servers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "drawio": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@drawio/mcp@latest"]
    }
  }
}

2. SKILL.md（Agent Skills）

畫面設計書的創建由兩個 MCP 組成的多步驟構成。
由於每個步驟所需的 MCP 是確定的，因此判斷在 SKILL.md 中嚴格記載步驟和使用工具可以使成果物更穩定，因此此次將基於 SKILL.md 進行。

準備了兩個 SKILL。

• 畫面設計書創建用：信息收集 → 截圖 → 佈局圖 → 設計書生成
• 畫面操作（Playwright）用：應用啟動確認・啟動・登錄・登出“基礎”

原因是，畫面操作部分可能在其他用途上也可以重複使用，而如果全部集中在一起，則內容過於龐大。

2-1. 畫面設計書創建用 SKILL

這裡將詳細寫出畫面設計書創建時的步驟。

• 收集目標畫面的信息
• 使用 Playwright 進行畫面操作和截圖拍攝
• 使用 draw.io 將截圖轉換為帶有項號的佈局圖
• 生成包括佈局圖和畫面項目的設計書（Markdown）

「請製作文件」可能會導致在失敗的情況下也未發現而繼續進行。因此，加上 PowerShell 的 存在檢查 或 嵌入驗證後穩定性會提高。

<details><summary>SKILL.md 記載內容</summary>

---
name: screen-design-doc-generator
description: 製作畫面設計書（Markdown）。使用 Playwright 獲取目標畫面的螢幕截圖，使用 drawio 在全螢幕截圖上新增項號（正方形+數字）的佈局圖（PNG），然後根據畫面項目・輸入規則・轉移・訊息沿用模板撰寫。當被要求創建畫面設計書時使用。
---

# 目的
以一定質量、粒度、格式製作 Web 應用的畫面設計書。

# 使用此技能的時機
- 當要求創建畫面設計書時

# 前提（需要的輸入）
用戶如有不足，請在作業開始前詢問並補充（不要依賴推測）。
- 目標畫面名稱（包含 <screen-name> 的命名）
- 畫面的 URL（如需登錄則提供步驟）
- 畫面的目的（誰的/誰在什麼時候使用的畫面）
- 主要用例（最多 3～5 個）
- 若存在現有的模板/資料夾結構請提供路徑

# 成果物（輸出）
下面的內容會創建/更新（路徑必須統一）。
- `documents/design/ui-design/<screen-name>.md`（畫面設計書）
- `documents/design/ui-design/assets/screens/<screen-name>_full.png`（全螢幕截圖）
- `documents/design/ui-design/assets/screens/<screen-name>_<n>.png`（額外截圖：選擇性）
- `documents/design/ui-design/assets/layouts/<screen-name>.png`（drawio 創建的佈局圖：全螢幕截圖+項號）
- `documents/design/ui-design/assets/layouts/<screen-name>.drawio`（可編輯的源文件）

# 作業步驟
## 1. 理解目標畫面
- 整理畫面的目的、使用者及前提條件（登錄/權限/預先數據）
- 列出畫面的主要用例（最多 3～5 個）

## 2. 使用 Playwright 獲取畫面截圖
- 打開畫面，拍攝初始顯示的全螢幕截圖
- 如果可能，以下內容也應拍攝（基於需求範圍）
  - 畫面內的模式視圖
  - 驗證錯誤顯示
  - 成功提示/失敗訊息
- 將獲取的圖片保存到 `documents/design/ui-design/assets/screens/` 中
  - 全螢幕截圖：`<screen-name>_full.png`
  - 其他：`<screen-name>_<n>.png`（n 從 1 開始的連號）

## 3. 使用 drawio 創建佈局圖（格式化版本）（在全螢幕截圖上附上項號）

### 3.0 目的
- 確保 `documents/design/ui-design/assets/layouts/<screen-name>.drawio` 中 **嵌入了全螢幕截圖**
- 確保 `documents/design/ui-design/assets/layouts/<screen-name>.png` 被 **確實導出**
- `<screen-name>.png` 是「以全螢幕截圖為底」和「項號（正方形）在最前面」合成的單幅圖片
- 項號的背景色需 **有透明度（Opacity）**

### 3.1 輸入圖片（底圖）的路徑（固定）
- 底圖圖片：`documents/design/ui-design/assets/screens/<screen-name>_full.png`

### 3.2 drawio 資源的創建和保存位置（固定）
- 資源：`documents/design/ui-design/assets/layouts/<screen-name>.drawio`

### 3.3 drawio 的操作（必需：圖片要“嵌入”）
1. 新建或打開 `documents/design/ui-design/assets/layouts/<screen-name>.drawio`
2. **嵌入圖片**以插入
   - 將 `documents/design/ui-design/assets/screens/<screen-name>_full.png` 插入到 drawio
   - 插入時若可選“鏈接”或“嵌入”，必須選擇 **嵌入（Embed）**
3. 將插入的圖片作為底圖格式化
   - 將圖片放置於頁面的左上角（原點）
   - 調整頁面尺寸以符合圖片，讓圖片做為整個頁面的底圖（如使用“適合內容 / Fit to content”等）
   - 將圖片移至 **最背面（Send to back）** 並鎖定（Lock）以防止後續移動

### 3.4 附加項號（正方形+數字）（必需：最前面・有透明度）
1. 項號使用 **正方形（square）**（禁止使用圓形或對話框）
2. 在正方形中間寫上數字（`1, 2, 3...`）
   - 文本需置中對齊
   - 正方形大小在所有項目中統一
3. 項號背景色需 **設置透明度（Opacity）**
   - 例如：Opacity 40〜60%（數值任意但必需有透明度）
4. 所有項號需統一為 **最前面（Bring to front）**
   - 底圖為最背面，項號為最前面
5. 項號需與“畫面項目表”中的項號一致

### 3.5 （選擇性）主要區域的邊框
- 可視需要為主要區域（標頭/搜索條件/列表/底部等）劃定邊框（選擇性）

### 3.6 保存（必需：.drawio 中包含圖片狀態的保存）
- 保存為 `documents/design/ui-design/assets/layouts/<screen-name>.drawio`
- 保存後，**一次關閉該 drawio 文件再重新打開**，確保顯示全螢幕截圖
  - 若未顯示，可能是因為選擇了“鏈接保存”，請務必重新以“嵌入”方式插入

### 3.7 PNG 輸出（必需：合成的單幅圖片）
- PNG 輸出路徑：`documents/design/ui-design/assets/layouts/<screen-name>.png`
- 導出的 PNG 需是 **“全螢幕截圖 + 正方形項號”合成的單幅圖片**
- 輸出時需針對整個頁面（Page）進行輸出（禁止僅輸出圖片/選擇範圍）

### 3.8 輸出／嵌入的驗證（必需：若失敗則重新操作）
使用以下 PowerShell 指令檢查成果物，若不符合需重做 3.6〜3.7。

```powershell
# 1) 確保 PNG 存在且不為 0 字節
$png = "documents/design/ui-design/assets/layouts/<screen-name>.png"
if (!(Test-Path $png)) { throw "PNG not exported: $png" }
if ((Get-Item $png).Length -le 0) { throw "PNG is empty: $png" }

# 2) 確保 drawio 存在
$drawio = "documents/design/ui-design/assets/layouts/<screen-name>.drawio"
if (!(Test-Path $drawio)) { throw "DRAWIO not saved: $drawio" }

# 3) 確認 drawio 中是否嵌入圖片（必須包含 data:image）
#    ※ 嵌入圖片通常以 data:image 格式存在於 drawio (XML) 中
if (!(Select-String -Path $drawio -Pattern "data:image" -Quiet)) {
  throw "Screenshot is likely NOT embedded in drawio: $drawio"
}
"OK: layout png exported and screenshot embedded"

• 若以上檢查未通過：
  • 重新以“嵌入”方式創建 .drawio → 保存 → PNG 輸出 → 再驗證

4. 創建 Markdown 設計書

• 根據模板進行撰寫
• 不要依賴推測，若有疑問需 明示為“需確認” 或詢問用戶以確定

5. 自我檢查（品質檢查）

• 項號在“佈局圖”和“畫面項目表”中保持一致
• 輸入規則（必填/位數/形式/範圍）無遺漏
• 按鈕/鏈接的行為（點擊後的轉移/更新/確認）清晰明確
• 文句（標籤/訊息）與畫面一致（若未確定則需確認）

畫面設計書模板（請遵守此結構）

## <畫面名> 畫面設計書

### 1. 概要
- 目的：
- 目標用戶：
- 前提條件：

### 2. 畫面佈局
<!-- 以全螢幕截圖為底加上正方形項號的佈局圖 -->
<img src="./assets/layouts/<screen-name>.png">

### 3. 畫面項目
| 項號 | 項目名稱 | 類型 | 顯示/輸入 | 必填 | 型別/形式 | 位數 | 初始值 | 輸入規則 | 備註 |
|---:|---|---|---|:--:|---|---:|---|---|---|
| 1 |  | 文本 | 輸入 |  |  |  |  |  |  |

### 4. 操作・事件
| 畫面項號 | 操作 | 觸發器 | 條件 | 處理內容 | 成功時 | 失敗時 |
|---|---|---|---|---|---|---|
| 1 | 搜索 | 點擊搜索按鈕 |  |  |  |  |

### 5. 補充
- 權限/角色：
- 性能/限制：
- 需確認事項：

2-2. 畫面操作（Playwright）用 SKILL

這裡將確保 Playwright 能夠順利操作的狀態。（啟動確認→如有必要則啟動→登錄→操作→登出）

沒有這一步，Copilot 可能會陷入困境。

<details><summary>SKILL.md 記載內容</summary>

---
name: app-operation-playwright
description: 確保使用 Playwright（Playwright MCP）順利啟動、登錄、操作與登出本地 Web 應用（http://localhost:8080）所需的步驟
---

# 使用 Playwright 進行應用操作（畫面操作步驟）

## 此 SKILL 的前提（重要）
- 目標 URL：`http://localhost:8080`
- 應用啟動需以 **Windows PowerShell** 為前提（命令也以 PowerShell 記載）。
- 數據庫需 **存在 docker-compose.yml**，並啟動 MySQL（`todo-chat` / `todo-chat-test`）。
  - 不過 **不需要等候測試容器（todo-chat-test）的 health**（作為要求不必要）。
- 應用的啟動命令如下。
  - `cd .\webapp\`
  - `.\mvnw.cmd spring-boot:run`
- Java 的版本指定必須以下執行（固定 JDK 21）。
  - `$env:JAVA_HOME="C:\Program Files\Java\jdk-21"`
  - `$env:Path="$env:JAVA_HOME\bin;$env:Path"`

## 目的
- 讓 Copilot 使用 Playwright（Playwright MCP），能夠 **確認啟動狀態 → 如有必要則啟動 → 登錄 → 畫面操作 → 登出** 至少能夠準確執行。

## 禁止事項
- **禁止推測資格資料（ID/密碼）**（若找不到應停止並確認用戶）
- **禁止破壞性操作**（例如：刪除、退會、收費、管理者操作、數據更改等）

## Playwright 的元素特定規則（本應用前提）
此應用的 HTML 中沒有 `data-testid` 等測試用屬性，故按照以下順序進行特定。

1. 與標籤相關的輸入（`label` → `input`）
2. **placeholder**（輸入欄的提示文字）
3. **name / id** 屬性（如表單部件有持有的情況下）
4. **按鈕或鏈接的顯示文本**（例如：`Login` / `登出`）

不使用 `nth-child` 或過於長的 CSS 選擇器

---

# 作業步驟

## 1. 事前確認“是否已啟動”（確保檢查）

### 1.1 HTTP 疏通檢查（最優先）
如 **返回 HTTP 200/3xx 則表明已啟動**。

```powershell
try {
  $r = Invoke-WebRequest -UseBasicParsing http://localhost:8080/ -TimeoutSec 3
  $r.StatusCode
} catch {
  "NOT_RUNNING"
}

• 若結果顯示 NOT_RUNNING → 請進入「2. 啟動步驟」

1.2 確認 8080 是否 LISTEN（輔助）

netstat -ano | Select-String ":8080"

1.3 確認 docker-compose 的容器啟動（輔助：數據庫啟動判斷）

docker-compose.yml 是用於數據庫的。

docker compose -f .\docker-compose.yml ps

2. 啟動步驟（若未啟動的話）

2.1 前提：必須指定 Java 21

$env:JAVA_HOME="C:\Program Files\Java\jdk-21"
$env:Path="$env:JAVA_HOME\bin;$env:Path"
java -version

• 確認 java -version 的輸出中必須包含 21。

2.2 透過 docker compose 啟動數據庫（確定步驟）

2.2.1 執行 docker compose （啟動數據庫）

docker compose -f .\docker-compose.yml up -d
docker compose -f .\docker-compose.yml ps

2.2.2 關於測試容器（todo-chat-test）

• todo-chat-test 為測試用途，故 不等待其 health。
• 只要能在 docker compose ps 中確認到類似生產的數據庫 todo-chat 正在啟動即可。

2.3 啟動應用（Web）的命令（確定命令）

cd .\webapp\
.\mvnw.cmd spring-boot:run

2.4 確認啟動完成後（HTTP 回應）（確定等待）

啟動應用後，等待 http://localhost:8080/ 的回應。

for ($i=0; $i -lt 120; $i++) {
  try {
    $r = Invoke-WebRequest -UseBasicParsing http://localhost:8080/ -TimeoutSec 2
    if ($r.StatusCode -ge 200 -and $r.StatusCode -lt 400) { "OK: app is up"; break }
  } catch {}
  Start-Sleep -Seconds 1
}

3. 登錄步驟（Playwright：確保流程）

3.1 判定登錄需求（確保條件）

1. 使用 Playwright 打開 http://localhost:8080

2. 透過以下來決定是否為登錄畫面

   • URL 路徑和 http://localhost:8080/login 一致

• 若為登錄畫面 → 進入 3.2
• 其他情況 → 視為已登錄，進入 4

3.2 執行登錄（從 .env 讀取憑證）

3.2.1 憑證（確定信息）

憑證從 .env 的以下鍵中獲取（確定）。

3.2.2 UI 操作（使用 REPLACE_ME 進行元素特定）

1. 使用 #username 特定使用者名稱輸入欄並輸入 username
2. 使用 #password 特定密碼輸入欄並輸入 password
3. 點擊按鈕顯示文本為 Login 的元素
4. 成功判定（必需）：
   • URL 路徑變更為非 http://localhost:8080/home 或
   • 顯示登出鏈接（Logout）

3.3 登錄失敗時（確保應對）

• 若點擊後仍顯示登錄畫面：

  1. 獲取畫面上顯示的錯誤訊息並記錄（同時獲取螢幕截圖）
  2. 請用戶確認 .env 的 APP_USERNAME / APP_PASSWORD 是否正確
  3. 若顯示 CAPTCHA/MFA/SSO，則固定為無法自動化，請用戶指示

4. 目標畫面操作（選擇性）

• 操作目標及成功條件（URL 變化 / 元素顯示 / 提示顯示等）必須在執行前明確定義。

5. 登出步驟（Playwright：確保流程）

5.1 判定登出導向

• 點擊顯示文本為 Logout 的元素。

5.2 成功判定（必需）

根據以下判定。

• URL 路徑變更為 http://localhost:8080/login

6. 故障排除（確保能夠精確區分）

6.1 無法連接至 http://localhost:8080

1. 重新檢查 1.1 的 HTTP 檢查
2. 檢查 2.2 數據庫是否已啟動（docker compose ps）
3. 確認 2.3 的應用啟動 (.\mvnw.cmd spring-boot:run) 是否仍運行（檢查啟動終端的日誌）
4. 確認 8080 端口沒有被他進程佔用（1.2）

6.2 docker compose 無法啟動

• 檢查 docker compose -f .\docker-compose.yml logs --tail=200，確認環境變數（MYSQL_*, TZ）是否正確解決

6.3 找不到 UI 元素 / 無法點擊

• 獲取螢幕截圖以確認“當前顯示的文句 / 標籤 / placeholder / name / id / aria-label”。
• 若需等待，請明確等待條件（元素顯示/隱藏）後再等待。

7. 執行檢查清單（完成條件）

• [ ] Java 21 啟用（java -version 中含有 21）
• [ ] docker compose -f .\docker-compose.yml ps 中 todo-chat 狀態為 running
• [ ] http://localhost:8080/ 返回 200/3xx 回應
• [ ] 滿足登錄成功判定（URL 或顯示登出鏈接）
• [ ] 滿足登出成功判定（URL 或顯示登錄畫面識別元素）

  
  </details>

補充（憑證和作業系統差異）

儘管 Copilot 透過讀取 .env 獲取憑證，但將其分離為類似 .env.copilot 的 供 Copilot 使用 是較理想的選擇。
此次以 Windows 為前提，因此若考慮 Mac/Linux，則需要將命令部分的記載獨立出來。

成果物

創建 SKILL 後，接下來只需將希望創建的畫面信息丟給 Chat。

# 依頼內容
請製作任務列表的畫面設計書。

# 前提
- 畫面名稱: 任務列表
- URL: http://localhost:8080/task
- 畫面的目的: 列出登錄用戶創建的任務，並提供搜索功能
- 主要用例
  - 搜索任務
    - 搜索項目包括標題、狀態、開始時間的 From~To、結束時間的 From~To
    - 除標題外，其他項目為詳細搜索項目
  - 當前顯示的任務可以轉至參考畫面
- HTML 路徑: webapp/src/main/resources/templates/task/index.html

約 20 分鐘後，生成了以下 5 個文件。

task-list.md 大約是這樣的格式。

總結

首先是好的地方

• 除了佈局圖的生成之外，幾乎完美
  • 生成的畫面設計書結構符合 SKILL.md 中記載的模板
  • 設計書中應記載的畫面項目的取捨也相當準確
  • 搜索項目全數覆蓋
  • 對於未記載的標頭或底部部分項目也能準確附上項號
  • 操作・事件部分的記載內容完美
  • 與畫面項號的關聯無誤
  • 處理內容與實作一致

總之，由於 Playwright 的畫面操作成立且文句（規格記載）穩定正確，從沒有畫面設計書的狀態來 0 → 1 的創造用途相當有效。
即使佈局圖未完成，只要手動修正生成的 documents/design/ui-design/assets/layouts/<screen-name>.drawio，即可把設計書完成。

然後，剩下的遺憾

• 由於 “各畫面項號未堆疊於各自上方”
  • 雖然項號可以針對全螢幕截圖進行附加，但 項號未能置於應指向的項目位置，而是在偏離位置繪製。
• 未能獲取搜索結果數量為 0 的截圖。

如果仍然存在這兩點，則 在已有畫面設計書的“更新（維護）目標”下尚嫌早。
在已有設計書的情況下，這次的“文句面正確記載”經常已符合要求，更新的難點反而是 畫面佈局（截圖/項號/位置）的跟隨，因此若那部分不穩定使用上會有所不便。

接下來該怎麼做？

• 針對額外需要的截圖（例如：搜索結果 0、驗證）應在 Chat 輸入端明示以減少遺漏。
• 提升佈局圖中“項號堆積於項目上方”的精確度，或許可考慮將 基於座標的排放機制 化。
  • 例如，從 HTML 獲取元素的位置信息，然後在 Playwright 端進行項號堆積等。

儘管如此，目前在提示側仍有改善空間，也將著手進行改進。
感謝您閱讀到最後！！

原文出處：https://qiita.com/Ymmy/items/1d84037b3b9a499167de