啟用合約
每當使用者以一般文字提出 UI 設計、Mockup、畫面、登陸頁面或視覺方向的要求，或針對 design/ 下的畫板進行迭代時，預設啟用此技能。不要用它來實作專案技術棧中的正式程式碼。
/gentle:design 指令是選用捷徑：所有動作皆可透過一般請求搭配此技能與 gentle_design 工具（list、open、stop、implement、handoff）完成。
硬性規則
- 每個畫板都是一個自包含的 HTML 檔案：內嵌 CSS、JS 與 SVG；僅使用系統字體堆疊。絕不引用外部 URL、CDN、遠端字型、圖片或腳本。
- 使用針對目標受眾的真實內容；禁止使用 Lorem Ipsum 或佔位名稱。
- 無障礙標記：使用語意化元素與地標、符合 WCAG AA 對比度、可見的焦點樣式、尊重
prefers-reduced-motion設定（若有動畫）。 - 當
design/system.md存在時，先讀取它，並僅使用其中的 Token 與元件規則；在完成任何畫板前執行「設計系統同步」中的自我檢查。 - 最多提出一個釐清問題，且僅在需求不明確（缺乏目標或內容）時提出。
- 迭代時僅編輯指定的畫板。絕不重寫其他畫板。
決策閘門
| 情況 | 動作 |
|---|---|
| 新的需求簡報 | 撰寫 N 個（預設 3 個，或依要求數量）明顯不同的設計方向，存入新的 design/<slug>/ |
| 對某個畫板的意見回饋 | 僅編輯該檔案；保留其清單項目，若權衡取捨有變則更新 tradeoff |
| 「儲存並嘗試不同方法」 | 以接下來的 NN 新增一個畫板；保留先前畫板；將其附加至清單 |
| 使用者想調整數值（間距、色彩、字體級數） | 在畫板中加入滑桿或控制項，以及一個「複製為提示詞」按鈕，可將選定數值複製為提示詞 |
新需求簡報的 design/<slug>/ 已存在 | 選取新的 slug；絕不覆蓋其他設計 |
| 訊息附帶設計評論，或使用者要求套用評論 | 遵循下方的「Canvas 註解」 |
/gentle:design sync，或使用者要求擷取專案的設計系統 | 遵循下方的「設計系統同步」 |
| 使用者要求顯示、停止或列出設計，或實作一個畫板 | 呼叫 gentle_design 工具（open、stop、list 或 implement，參數為 <slug>/<artboard>）；遵循 implement 回傳的交接文字，並以 action "handoff" 回報進度：開始時 status: "in_progress"，完成時 status: "implemented"，若執行中的應用程式有回送 URL 則將 previewUrl 設為該 URL |
設計前
在每次新的需求簡報前執行此閘門：呼叫 gentle_design 工具，參數為 action: "list"，然後：
list 回報 | 動作 |
|---|---|
system.exists 為 false 且 designSources 存在 | 先執行「設計系統同步」，用一句話告知使用者已同步專案的設計系統，然後再依此設計 |
無 designSources | 跳過同步並自由設計 |
system.staleSources 存在 | 列出那些來源，說明 design/system.md 可能已過期，並在設計前提議重新同步；僅在使用者同意後才重新同步，絕不默默使用過期的 Token |
執行步驟
- 理解需求簡報：目標、佈局、內容、受眾。
- 載入
gentle-ui-design：讀取其SKILL.md，以及僅與簡報的受眾、主要任務和成功條件相符的參考資料。此技能負責交付；該技能負責 UX 品質。 - 從簡報中選取一個 kebab-case 的 slug。
- 確保各方向在結構或視覺策略上有所不同，而不僅僅是顏色。為每個方向標註其做出的權衡取捨。
- 為每個畫板撰寫
design/<slug>/NN-<name>.html（01-…、02-…；名稱使用 kebab-case）。 - 撰寫
design/<slug>/design.json：
{
"title": "定價頁面",
"brief": "針對學生的筆記應用程式定價頁面",
"feature": "odd/tasks/pricing-page.md",
"artboards": [
{ "file": "01-comparison-table.html", "title": "比較表格", "tradeoff": "資訊密集且易於掃讀；情感吸引力較弱", "width": 1440, "height": 900 },
{ "file": "02-single-plan-hero.html", "title": "單一方案主視覺", "tradeoff": "焦點明確；隱藏方案差異", "width": 1440, "height": 900 }
]
}
- 將
width/height設為畫板預期的視口（以 CSS 像素為單位）；每次變更時保持清單與檔案同步。欄位：title、brief、選用feature，以及包含file、title、tradeoff、width、height的artboards[]。 - ODD 連結：當設計來自追蹤中的 ODD 功能（目前工作中已有的
odd/tasks/<feature>.md），將feature設為該路徑，並在該文件的## Log中附加一個條目，標註design/<slug>/及其畫板。當該設計的某個畫板被交接實作時，Log 條目也須註明被選中的畫板（被交接的那個；list會回報為Chosen）以及其他為替代方案。對於小型未追蹤的工作，省略feature並讓設計獨立存在；永遠不要為了連結而建立功能文件。 - UX 自我檢查：針對你完成的每個畫板，將其與
gentle-ui-design的構成與回饋（層次、密度、回饋）以及適應性介面（窄螢幕、輸入存取、狀態）指引進行比對，並在回報前修正所有差距。 - 在撰寫或變更畫板後，呼叫
gentle_design工具，參數為action: "open"與 slug，除非使用者要求不要這麼做。當 Canvas 分頁已開啟時，它會重新整理該分頁而非開新分頁，因此每次變更後都應呼叫。回報它傳回的 URL。
設計系統同步
- 僅讀取，絕不編輯專案原始碼。來源：CSS 自訂屬性（
:root、@theme、[data-theme]）、Tailwind 設定或 v4 的@theme、元件庫資料夾、現有的 Token 檔案，以及它們宣告的字型。 - 撰寫
design/system.md：色彩（Token 名稱、值、用途）、排版、間距、圓角、陰影與元件規則。每個條目都須標註其來源path。僅記錄在來源中找到的值。 - 撰寫
design/system.html：一個自包含的畫板，寬度 1440 px，呈現那些 Token（色票、字體級數比例、間距、圓角、陰影）與核心元件，遵守相同的無外部 URL 規則。Canvas 會將其顯示為每個設計的第一個面板。 - 當沒有設計來源存在時，說明情況並提議一個最小的起手系統供使用者接受；絕不能將發明出來的值作為專案 Token 呈現。
- 自我檢查：在
design/system.md存在的情況下，針對你完成的每個畫板：列出該畫板使用的色彩與字體家族，與系統 Token 比對，並在回報前修正所有偏差。
Canvas 註解
來自 Canvas 的註解儲存在 design/<slug>/comments.json 中；工作階段也會將它們作為訊息接收，每則訊息會標註註解 ID。
- 使用
gentle_design_comments工具（action: "list"，可選slug與file）讀取開啟中的註解。若無該工具，則讀取design/<slug>/comments.json，並使用status為"open"的條目。 - 透過僅編輯其
file中的畫板來套用每個註解；使用selector與excerpt找到對應元素。若註解有screenshot，先查看它：它會附加在註解訊息中，或使用讀取工具開啟design/<slug>/<screenshot>。它顯示使用者所見的內容，通常是靜態畫板無法呈現的瞬態動畫或轉換狀態。 - 使用工具將每個已套用的註解標記為已解決（
action: "resolve"、slug、ids）。若無該工具，則將其status設為"resolved"並將resolvedAt設為目前的 ISO 時間，保留其他所有條目與欄位不變。保留你未套用的註解為開啟狀態，並說明原因。
僅有檔案存取權限的代理適用的檔案格式：
{
"version": 1,
"comments": [
{ "id": "k3x9p2ab", "file": "02-bold.html", "selector": "body > header > h1", "excerpt": "Ship faster", "comment": "讓標題更短。", "createdAt": "2026-10-26T10:00:00.000Z", "status": "open", "sentAt": null, "resolvedAt": null },
{ "id": "m7q2w9cd", "file": "02-bold.html", "selector": "#cta", "excerpt": "Start", "comment": "按鈕在懸停過渡時會跳動。", "screenshot": ".screenshots/m7q2w9cd.png", "createdAt": "2026-10-26T10:05:00.000Z", "status": "open", "sentAt": null, "resolvedAt": null }
]
}
screenshot 為選用：相對於設計資料夾的路徑，位於 .screenshots/ 下，僅在使用者附加圖片時存在。
絕不刪除或重新排序條目，並保持檔案為有效的 JSON：Canvas 拒絕覆蓋無法解析的檔案。
輸出合約
回傳：slug、每個畫板檔案（含標題與權衡取捨）、本次變更的檔案、本次解決的註解 ID，以及任何未決問題。提供步驟 10 的 Canvas URL，或說明 /gentle:design open <slug> 可顯示 Canvas（若你並未開啟它）。對於同步作業，回傳已讀取的來源路徑、每個群組的 Token 計數，以及該系統是否為建議的起手系統；若是在「設計前」步驟中自動同步，則說明已執行並以同樣方式回報。
參考資料
- 專案中的
design/system.md（若存在）——須遵循的設計 Token。 gentle-ui-design技能——與每個畫板搭配使用的 UX 品質指引。