Google DESIGN.md 教學：把設計規則寫成檔案，再用 lint 與 diff 檢查
Google DESIGN.md 把顏色、字體與設計理由寫成可讀檔案。用官方 lint、diff 檢查格式與變更，再看十份小型實驗紀錄，了解工具能驗證什麼、哪些仍需人工判斷。
Google DESIGN.md 適合解決一個很具體的問題：同一個產品交給 AI 修改幾次之後，按鈕、顏色與字體開始各做各的。
只給一張參考圖，AI 仍得猜哪些視覺決定必須保留。把這些決定寫進檔案，之後每次改畫面，就有共同的依據可以對照。
Google Labs 開源的格式把設計數值和理由放在一起，也提供檢查指令。不過，寫了一個叫 DESIGN.md 的檔案，不代表內容已符合它的規格。
AI 郵報 11 月 14 日的小型實驗正好看見這個差別。相同品牌簡介，給不給官方規格，產生的檔案在格式檢查上有明顯差異。
這個結果適合用來建立提交前的檢查流程。至於設計好不好看、畫面是否真的照檔案呈現，仍須打開產品確認。
Google DESIGN.md 是什麼？先把數值與用途寫清楚
它是一份讓人與程式都能理解的設計說明。官方專案把結構化的設計數值和文字理由放在同一份檔案，讓 AI 既有數值可照，也知道如何使用。
例如主色可以叫 primary。因為名稱代表它在介面中的用途，色碼則是目前採用的值，所以之後換品牌色時，可以調整值，同時保留這個角色。
這類有名字的設計決定稱為 token。團隊可以用它描述顏色、字體等共同規則，減少每個元件自己選一組數值的情況。
數值採 YAML，一種用欄位和值表達資料的文字格式，可以寫在檔頭，也能放進各節的 YAML 程式碼區塊。固定欄位讓工具容易檢查，文字理由則幫助接手的人理解品牌的選擇。
所以，一份好讀的設計介紹，和一份可被官方工具檢查的檔案，有不同的要求。要讓兩者接上，應讓 AI 先讀正確格式。
lint、diff、export、spec 各做什麼？
最先用得上的通常是 lint 和 diff。前者檢查現在這份檔案，後者比較修改前後的檢查結果，讓團隊知道這次變更是否增加問題。
官方工具的四項用途如下，指令與格式以 README 的版本為準。
| 指令 | 用途 | 工作中適合放的位置 |
|---|---|---|
| lint | 檢查結構、引用及已定義的顏色配對 | AI 寫完檔案後 |
| diff | 比較兩版並辨認檢查結果是否退步 | 合併或提交變更前 |
| export | 把檔案轉成支援的輸出格式 | 接到既有設計或工程流程時 |
| spec | 印出格式規格 | 請 AI 建檔前 |
先讀 spec、再寫檔、最後跑 lint，比只要求「幫我產生 DESIGN.md」多了一個可核對的標準。如果已有舊版，就再用 diff 看這次修改。
執行前需要 Node.js，這是讓電腦執行 JavaScript 工具的環境。裝好後，可以在設計檔所在資料夾執行以下指令。
npx @google/design.md lint DESIGN.md
修改前先保存一份基準檔。新版本完成後，用以下指令比較兩份檔案；若錯誤或警告比基準增加，diff 就會以結束碼一回報。
npx @google/design.md diff DESIGN.md DESIGN-v2.md
官方仍把規格標為 alpha，意思是格式正在發展，之後可能變動。團隊應記錄使用的工具版本，避免把不同版本的結果直接混在一起比較。
十份檔案實驗：給了規格之後，有哪些差異？
這次實驗只比較格式檢查，沒有評選哪一組畫面更漂亮。AI 郵報在 11 月 14 日用同一份圖書館 App 品牌簡介，分兩組各產生五份設計檔。
A 組沒有提供官方規格，B 組先讀官方 spec 與當時列出的十一條規則。紀錄中的模型名稱由子代理自報為 Sonnet 5.5，沒有獨立驗證模型身分。
用當時 0.4.0 版的命令列工具檢查，結果如下。
| 條件 | 檔案結果 | 檢查結果 |
|---|---|---|
| A 組其中四份 | 數值寫在表格或 CSS 等位置 | 各有一項找不到 YAML 的警告 |
| A 組剩下一份 | 有 YAML，但部分欄位不符規格 | 十七項警告 |
| B 組五份 | 都有可辨讀的規格結構 | 錯誤與警告均為零 |
這裡的關鍵是警告的含義。A 組四份找不到 YAML，工具仍記為 warning，而非 error，所以不能把結果描述成四份程式執行失敗。
B 組的零錯誤、零警告，也只說明通過當時工具涵蓋的檢查。它沒有證明整套設計完整，也沒有證明生成後的介面符合檔案。
樣本只有一份品牌需求，每組五份。這足以提醒團隊應把規格交給 AI，但不足以估計所有模型、所有品牌的成功率。
改壞一份檔案，檢查器能指出哪裡退步？
有了可檢查的基準版，才比較容易辨認後續修改造成的問題。實驗另外改動一份檔案，放入不存在的顏色引用、調淡次要文字，並加入沒有元件使用的顏色。
這次 lint 回報一個錯誤、兩個警告。diff 的結果標示 regression 為 true，並以結束碼一回報。結束碼是指令執行後交給其他程式的狀態值，可讓自動流程決定是否繼續。
這代表團隊可以把檢查接在提交前。當修改增加問題，就先停下來看差異，再決定要修正或接受變更。
不過，顏色對比檢查有範圍。官方規則主要檢查檔案裡元件所指定的背景色與文字色配對，並不等於掃過完整網站所有狀態。
如果畫面有透明層、圖片背景、不同互動狀態，還是要到渲染後的頁面檢查。規格檔幫助團隊保留設計決定，實際畫面則回答決定有沒有被正確實作。
什麼情況值得先做一份規則檔？
當同一產品會持續交給不同人或 AI 修改，規則檔很有用。主色、文字層級與元件慣例有共同依據，接手時就少一輪猜測。
如果還在探索風格，可以先保留少量已決定的規則。等畫面方向確定，再逐步補充，比一開始寫滿尚未拍板的數值更容易維護。
建議從一個已有畫面的頁面開始，把實際採用的決定寫進檔案，跑檢查後，再讓 AI 改一個元件。對照檔案與畫面，確認兩邊說的是同一件事。
動態與互動需求仍須另外描述，因為一份靜態規則無法代替操作驗收。
延伸閱讀：AI 設計參考怎麼給？從靜態截圖、動態影片到互動狀態的驗收清單
常見問題
通過 Google DESIGN.md 檢查，就代表設計完成嗎？
不代表。工具能核對的是它定義的格式、引用與部分配對規則。資訊層級、內容長短、實際互動及品牌是否合適，仍需人工檢視。
已有自己的設計文件，需要全部換掉嗎？
可以先在一個小範圍試用。如果原本文件已支援團隊協作，就先確認新格式能補上哪些自動檢查，再決定如何整合，無須為了檔名搬動整套資料。
零警告後，還需要用其他工具嗎？
如果目標是可用的網站，仍需要檢查實際頁面。像鍵盤操作、文字對比與行動版排版，應在產品上確認。
先讓一個元件走完「規則、改動、檢查」
這套方法適合想讓 AI 改版有依據的團隊。先選一個常被改動的元件，留下規則與基準版，再用 lint 和 diff 檢查下一次修改，會比一次寫完整套設計系統更容易看出價值。
想先釐清不同文件如何分工，可從 Google 的 Markdown 工作流開始，再回來決定哪些視覺規則值得保存。
延伸閱讀：Google 分享三種 Markdown 分工：AGENTS.md、DESIGN.md、SKILL.md 怎麼寫？
