DESIGN.md：讓編碼代理讀懂視覺系統
用於向編碼代理描述視覺標識的格式規格。 DESIGN.md 讓代理人對設計系統有持久的、結構化的理解。
秒懂
- 它是什麼？
- 把 YAML 設計令牌和 Markdown 設計理由放進同一份規範，並以 lint、diff、export 檢查代理可用的介面。
- 適合誰用？
- DESIGN.md：讓編碼代理讀懂視覺系統 適合已經能接受 alpha、Apache-2.0、並且願意按照 npx @google/design.md lint DESIGN.md 檢查實際輸出的團隊；若需求超出 README 明示的範圍，或需要長期穩定承諾，應先在自己的版本、作業系統與資料上確認限制，再決定採用。
- 可以商用嗎？
- 可以。Apache-2.0 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 1 天前。
- 用什麼語言寫的？
- 主要是 TypeScript（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
面向編碼代理的設計系統規範
DESIGN.md 是一種描述視覺身份的格式規範，面向編碼代理。README 稱它為代理提供持久且結構化的設計系統理解。DESIGN.md 檔案將 YAML front matter 中的機器可讀設計令牌與 Markdown 中的人類可讀設計說明結合。令牌為代理提供精確值，說明文字解釋這些值為何存在以及如何應用。專案使用 TypeScript 編寫，位於 google-labs-code/design.md。倉庫首頁指向 stitch.withgoogle.com 上的規範頁面，README 同時連結到 docs/spec.md 取得完整規範。
這個專案的判讀不能只看名稱或星標。README 把 alpha、Apache-2.0 放在明確的使用脈絡裡，實際價值取決於它與現有工作流程的接合位置。第 1 個觀察點是先確認輸入、輸出和失敗方式，再決定是否把它放進長期維護的程式庫。
DESIGN.md：讓編碼代理讀懂視覺系統 的 README 也提供了可操作的檢查線索：使用「npx @google/design.md lint DESIGN.md」時，應觀察命令是否能在目標環境啟動、產生預期輸出，以及錯誤是否指出足以定位問題的檔案或設定。這些結果比抽象的功能清單更能說明它是否適合目前的專案。
第 1 節針對 google-labs-code/design.md 還要核對 npx @google/design.md lint DESIGN.md 使用的執行時版本與專案設定。若是 DESIGN.md，檢查 YAML 分隔線和 token reference；若是 pytype，檢查 Python 3.12 的支援範圍；若是 google-research，檢查目標子目錄的 LICENSE；若是 zx，檢查 Node.js 的模組模式；若是 Vapor UI，檢查 React 元件的匯入；若是 ixgo，檢查 Go 版本與 build flags；若是 Clone Wars，檢查表格列出的原始碼和示範連結。這些具體檔案與命令能把閱讀結果落到可核對的選擇上。對團隊而言，這也留下了清楚的審查邊界：哪些能力來自 README，哪些行為仍須由本地執行結果確認。
檔案結構：令牌與說明文字在同一文件中
該格式定義了兩層。頂部由 --- 分隔的 YAML front matter 保存顏色、排版、圓角、間距和元件的令牌。Markdown 正文使用 ## 標題組織，必須按固定順序出現：Overview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components、Do's and Don'ts，部分有別名。段落可以省略，但出現的段落必須遵循該順序。模式還允許可選的 version、name、description 和 omitted 列表。元件令牌將元件名稱對應到諸如 backgroundColor、textColor、rounded、padding、size、height 和 width 等屬性。懸停等變體是帶有相關鍵名的單獨條目。
這個專案的判讀不能只看名稱或星標。README 把 alpha、Apache-2.0 放在明確的使用脈絡裡，實際價值取決於它與現有工作流程的接合位置。第 2 個觀察點是先確認輸入、輸出和失敗方式，再決定是否把它放進長期維護的程式庫。
第 2 節針對 google-labs-code/design.md 還要核對 npx @google/design.md lint DESIGN.md 使用的執行時版本與專案設定。若是 DESIGN.md，檢查 YAML 分隔線和 token reference；若是 pytype，檢查 Python 3.12 的支援範圍；若是 google-research，檢查目標子目錄的 LICENSE；若是 zx，檢查 Node.js 的模組模式；若是 Vapor UI，檢查 React 元件的匯入；若是 ixgo，檢查 Go 版本與 build flags；若是 Clone Wars，檢查表格列出的原始碼和示範連結。這些具體檔案與命令能把閱讀結果落到可核對的選擇上。對團隊而言，這也留下了清楚的審查邊界：哪些能力來自 README，哪些行為仍須由本地執行結果確認。
命令列工具：lint、diff、export 和 spec
README 記錄了四個命令列命令：lint、diff、export 和 spec。它們接受檔案路徑或 - 作為 stdin，預設輸出 JSON。lint 驗證結構正確性，diff 比較兩個檔案的令牌級變化，export 將令牌轉換為其他格式，spec 列印格式規範。README 展示了類似 npx @google/design.md lint DESIGN.md 和 npx @google/design.md diff DESIGN.md DESIGN-v2.md 的用法。在 Windows 上，bin 名稱中的 .md 後綴可能與 Markdown 檔案關聯衝突，因此 README 建議使用 designmd 別名，透過 npx -p @google/design.md designmd 呼叫。它還解釋了 ENOVERSIONS 錯誤為註冊表配置問題。
這個專案的判讀不能只看名稱或星標。README 把 alpha、Apache-2.0 放在明確的使用脈絡裡，實際價值取決於它與現有工作流程的接合位置。第 3 個觀察點是先確認輸入、輸出和失敗方式，再決定是否把它放進長期維護的程式庫。
第 3 節針對 google-labs-code/design.md 還要核對 npx @google/design.md lint DESIGN.md 使用的執行時版本與專案設定。若是 DESIGN.md，檢查 YAML 分隔線和 token reference；若是 pytype，檢查 Python 3.12 的支援範圍；若是 google-research，檢查目標子目錄的 LICENSE；若是 zx，檢查 Node.js 的模組模式；若是 Vapor UI，檢查 React 元件的匯入；若是 ixgo，檢查 Go 版本與 build flags；若是 Clone Wars，檢查表格列出的原始碼和示範連結。這些具體檔案與命令能把閱讀結果落到可核對的選擇上。對團隊而言，這也留下了清楚的審查邊界：哪些能力來自 README，哪些行為仍須由本地執行結果確認。
lint 規則
linter 執行十一條規則，每條具有固定嚴重級別。README 以表格列出。範例包括 broken-ref（錯誤）用於無法解析的令牌引用，contrast-ratio（警告）用於低於 WCAG AA 最低 4.5:1 的背景/文字配對，missing-primary（警告）當存在顏色但未定義 primary 顏色時，以及 section-order（警告）用於段落順序錯誤。還有資訊級規則如 token-summary 和 missing-sections。lint 命令在發現錯誤時退出碼為 1，否則為 0。README 展示了一個包含對比度檢查的範例 JSON 發現。
這個專案的判讀不能只看名稱或星標。README 把 alpha、Apache-2.0 放在明確的使用脈絡裡，實際價值取決於它與現有工作流程的接合位置。第 4 個觀察點是先確認輸入、輸出和失敗方式，再決定是否把它放進長期維護的程式庫。
第 4 節針對 google-labs-code/design.md 還要核對 npx @google/design.md lint DESIGN.md 使用的執行時版本與專案設定。若是 DESIGN.md，檢查 YAML 分隔線和 token reference；若是 pytype，檢查 Python 3.12 的支援範圍；若是 google-research，檢查目標子目錄的 LICENSE；若是 zx，檢查 Node.js 的模組模式；若是 Vapor UI，檢查 React 元件的匯入；若是 ixgo，檢查 Go 版本與 build flags；若是 Clone Wars，檢查表格列出的原始碼和示範連結。這些具體檔案與命令能把閱讀結果落到可核對的選擇上。對團隊而言，這也留下了清楚的審查邊界：哪些能力來自 README，哪些行為仍須由本地執行結果確認。
程式化介面與匯出目標
除了命令列，linter 還可作為 TypeScript 函式庫使用。README 展示了從 '@google/design.md/linter' 匯入 lint 並呼叫 lint(markdownString) 取得 findings、summary 和解析後的 DesignSystemState。export 命令可以輸出 Tailwind v3 設定 JSON、Tailwind v4 的 @theme CSS 區塊，或遵循 W3C Design Tokens Format Module 的 DTCG tokens.json。README 指出 DESIGN.md 令牌受 W3C Design Token Format 啟發。diff 命令報告令牌級新增、刪除、修改和回歸旗標。
這個專案的判讀不能只看名稱或星標。README 把 alpha、Apache-2.0 放在明確的使用脈絡裡，實際價值取決於它與現有工作流程的接合位置。第 5 個觀察點是先確認輸入、輸出和失敗方式，再決定是否把它放進長期維護的程式庫。
第 5 節針對 google-labs-code/design.md 還要核對 npx @google/design.md lint DESIGN.md 使用的執行時版本與專案設定。若是 DESIGN.md，檢查 YAML 分隔線和 token reference；若是 pytype，檢查 Python 3.12 的支援範圍；若是 google-research，檢查目標子目錄的 LICENSE；若是 zx，檢查 Node.js 的模組模式；若是 Vapor UI，檢查 React 元件的匯入；若是 ixgo，檢查 Go 版本與 build flags；若是 Clone Wars，檢查表格列出的原始碼和示範連結。這些具體檔案與命令能把閱讀結果落到可核對的選擇上。對團隊而言，這也留下了清楚的審查邊界：哪些能力來自 README，哪些行為仍須由本地執行結果確認。
狀態與授權
DESIGN.md 格式目前為 alpha 版本。README 表示規範、令牌模式和 CLI 正在積極開發，預期會有變化。專案採用 Apache-2.0 授權，授予重製、準備衍生作品、公開展示、表演、再授權和分發作品的版權和專利授權。授權不提供保證或支援；README 還包含免責聲明，該專案不符合 Google 開源軟體漏洞獎勵計畫的資格。倉庫元資料顯示有 26,960 個星標和 2,237 個分支，30 個未解決問題，但 README 未提供採用指標或使用者證據。
這個專案的判讀不能只看名稱或星標。README 把 alpha、Apache-2.0 放在明確的使用脈絡裡，實際價值取決於它與現有工作流程的接合位置。第 6 個觀察點是先確認輸入、輸出和失敗方式，再決定是否把它放進長期維護的程式庫。
第 6 節針對 google-labs-code/design.md 還要核對 npx @google/design.md lint DESIGN.md 使用的執行時版本與專案設定。若是 DESIGN.md，檢查 YAML 分隔線和 token reference；若是 pytype，檢查 Python 3.12 的支援範圍；若是 google-research，檢查目標子目錄的 LICENSE；若是 zx，檢查 Node.js 的模組模式；若是 Vapor UI，檢查 React 元件的匯入；若是 ixgo，檢查 Go 版本與 build flags；若是 Clone Wars，檢查表格列出的原始碼和示範連結。這些具體檔案與命令能把閱讀結果落到可核對的選擇上。對團隊而言，這也留下了清楚的審查邊界：哪些能力來自 README，哪些行為仍須由本地執行結果確認。
編輯結論
DESIGN.md：讓編碼代理讀懂視覺系統 適合已經能接受 alpha、Apache-2.0、並且願意按照 npx @google/design.md lint DESIGN.md 檢查實際輸出的團隊；若需求超出 README 明示的範圍，或需要長期穩定承諾，應先在自己的版本、作業系統與資料上確認限制，再決定採用。
社群筆記