design-md · DESIGN.md 設計契約工作流
把「設計決策」從散落的樣式程式碼裡抽出來，沉澱成 DESIGN.md——一份 AI agent 與人都能讀的 設計契約。本 skill 覆蓋完整閉環：
研究（可選聯網） → 提煉（extract） → 生成（scaffold） → 應用到程式碼 → 驗收（verify） → CI 門禁
DESIGN.md 是 Google Stitch 提出的概念：純文字設計系統文件，放在專案根目錄， 任何 AI coding agent 讀了之後產出的 UI 都能保持視覺一致。
AGENTS.md管「怎麼建構」，DESIGN.md管「長什麼樣」。
目錄結構
| 位置 | 用途 |
|---|---|
scripts/wcag.py | WCAG 2.1 對比度引擎：解析 tokens.css / design-tokens.json，自動按約定配對核算（文字 4.5:1、UI 3:1），exit code 可直接當 CI 門禁 |
scripts/extract.py | 從任意 URL 提煉設計令牌草稿（配色排名 / 字體堆疊 / 圓角），產出 tokens-draft.json + DESIGN.draft.md 骨架 |
scripts/scaffold.py | 從令牌 JSON 一鍵生成：tokens.css（雙形式令牌）+ tailwind.extend.js + preview.html 視覺化目錄 + 對比度報告 |
scripts/fetch_ref.py | 從 awesome-design-md 拉取參考 DESIGN.md（84 個品牌，raw → gh api 雙通道回退） |
scripts/research.py | DeepSeek Search/Fetch 聯網研究（計費直連、預設關閉：需使用者明確同意後帶 --yes-billing；金鑰從本機檔案 / 環境變數讀取，永不回顯） |
references/spec.md | DESIGN.md 檔案規範：frontmatter + YAML 令牌 + 11 節正文 + 寫法規則 |
references/lessons.md | 血淚教訓集：雙形式令牌、alpha 稀釋陷阱、accent 拆分、資料契約等（來自真實生產審計） |
references/research.md | DeepSeek Search/Fetch API 用法 + awesome-design-md 參考庫目錄（84 slug 全量） |
references/verify.md | 驗收清單 + CI 接線模板（npm script / GitHub Actions） |
templates/design-tokens.example.json | 可直接跑通的輸入範例（雙主題、全部通過 AA），照它改即可 |
快速開始
# 0) 環境：python3 ≥ 3.9，僅用標準庫
python3 scripts/wcag.py --help
# 1) 研究（可選）：從參考站點提煉令牌草稿
python3 scripts/extract.py --url https://example.com --out-dir ./design-draft
# → design-draft/tokens-draft.json + design-draft/DESIGN.draft.md
# 2) 拉一個知名品牌 DESIGN.md 當參考（當靈感，不當抄襲）
python3 scripts/fetch_ref.py --list # 看 84 個 slug
python3 scripts/fetch_ref.py --slug linear.app # → ./DESIGN.reference-linear.app.md
# 2b) （可選）DeepSeek 聯網研究——付費直連（5 元/1000 次成功請求），預設關閉：
# 僅當使用者明確同意後，才帶 --yes-billing 執行；金鑰由本機檔案提供，永不進對話/日誌
python3 scripts/research.py --yes-billing check # 驗證金鑰（預設讀 %USERPROFILE%\.deepseek\api_key）
python3 scripts/research.py --yes-billing search --query "fintech dashboard design site:dribbble.com" --count 8
# 3) 生成完整令牌工程（以你對齊後的 tokens JSON 為輸入）
python3 scripts/scaffold.py --tokens my-tokens.json --out ./design-out
# → tokens.css / design-tokens.json / tailwind.extend.js / preview.html / contrast-report.txt
# 4) 驗收（獨立跑，也可接 CI）
python3 scripts/wcag.py --tokens ./design-out/tokens.css # CSS 輸入
python3 scripts/wcag.py --tokens ./design-out/design-tokens.json # JSON 輸入
python3 scripts/wcag.py --pair "#E6E9EF:#0A0C10:4.5" # 單對 hex 速查
標準工作流（給 agent 的執行順序）
- 定需求：讀專案現狀（有沒有 DESIGN.md / tokens / 元件庫），明確主題方向（暗色優先？品牌色？行業調性——金融/開發者工具/醫療…）。
- 研究（可選）：用
references/research.md裡的方法做設計研究——DeepSeek Search 找參考站點（付費直連且預設關閉：先向使用者展示費用口徑並取得明確同意，才能帶 --yes-billing；未同意則一律走內建抓取），DeepSeek Fetch / 內建抓取把頁面轉 Markdown 細讀；從 awesome-design-md 拉 1-3 個同行業 DESIGN.md 參考。 - 提煉/起草：
extract.py出草稿 → 按references/spec.md的 11 節結構人工/agent 歸併角色（把「出現 200 次的 #5e6ad2」變成「品牌主色，用於 CTA 與焦點環」）。 - 生成：整理成規範 tokens JSON →
scaffold.py產出全套工程檔案（含預覽頁給使用者看效果）。 - 應用：把 tokens.css / tailwind 映射接進專案；元件按 DESIGN.md §4 的元件規則實現。
- 驗收：
wcag.py全綠 +references/verify.md清單逐項過；把門禁接進 CI（見 verify.md 模板）。 - 迭代：改任何色值 → 必須重跑
wcag.py，不憑觀感；設計決策變更寫回 DESIGN.md（版本註記）。
硬規則（務必遵守）
- 對比度不靠觀感：任何顏色改動都要跑
wcag.py。文字 ≥4.5:1，UI 控制項/邊框 ≥3:1。 - 雙形式令牌：每個顏色同時輸出
--x（hex）與--x-rgb（通道），否則 Tailwind 透明度修飾符靜默失效（詳見 lessons.md #1）。 - 不要用
bg-{warn}/10之類的 alpha 稀釋做淺底——淺底必須是獨立令牌（--warn-soft）。實測稀釋法在淺色主題下對比度反而惡化。 - 品牌色拆兩檔：
--accent（文字/連結）與--accent-solid（實底按鈕）。同一個值不可能同時滿足「暗背景上的亮文字」和「白字下的暗底」兩個 ≥4.5:1。 - 可互動邊界用
--border-strong（3:1），--border只做裝飾性分隔。 - 誠實標註 Known Gaps：沒提取到的（表單錯誤態、亮色版、私有字體替代）如實寫進 DESIGN.md，不裝完整。
- 參考 ≠ 照抄：awesome-design-md 的分析對象是各品牌的公開 CSS 特徵；引用時讀它們的「方法」（層級、節奏、取捨），不要冒充品牌身份；商業專案注意商標與字體授權。
安全
- 絕不回顯任何 API Key。金鑰解析順序：
--key-file→ 環境變數DEEPSEEK_API_KEY→ 環境變數DEEPSEEK_API_KEY_FILE→ 預設檔案%USERPROFILE%\.deepseek\api_key（推薦讓使用者 自行在終端建立，金鑰不經過對話/日誌）。research.py全鏈路輸出做sk-***遮罩。 - 計費保護（預設關閉，2026-10）：DeepSeek Search/Fetch 為直連計費 API（各 5 元/1000 次
成功請求；帳號級 Search 100 QPS / Fetch 25 QPS）。
research.py未帶--yes-billing（且環境變數DEEPSEEK_BILLING_CONSENT非1）時直接拒絕執行（exit 3）——agent 必須先 向使用者說明費用並取得明確同意，才可加旗標；opencode 等按量計費環境預設視為未同意。 - 未設定金鑰時不做 docstring 所謂的「必須聯網」假設——
extract.py走本地 urllib 抓取，DeepSeek 只是增強項。 - 抓取遵守 robots 與存取頻率；
extract.py預設最多抓 5 張樣式表、單張 512KB 上限。
與其他能力的關係
- awesome-design-md（VoltAgent，MIT）：84 個真實站點的 DESIGN.md 分析集合。本 skill 提供
fetch_ref.py一鍵取用；它是「參考素材庫」，本 skill 是「工作流程引擎」。 - DeepSeek Search/Fetch：
https://api.deepseek.com/v1/tools/search|fetch。設計研究階段的即時網頁檢索與正文抓取（含 site:/lang:/after: 語法）。按次計費（5 元/1000 次成功請求——僅「返回 200 且結果非空」計費，失敗/超時/空結果不計費）。帳號級限速 Search 100 QPS / Fetch 25 QPS（超出返回 429，research.py自動退避重試）。本 skill 提供scripts/research.py封裝呼叫（金鑰永不回顯；預設關閉——需使用者明確同意並帶--yes-billing，見 §安全）。 - Google Stitch 官方 lint（可選）：
npx @google/design.md lint DESIGN.md。