Design Md

編寫、驗證、比對和導出 DESIGN.md 文件 —— 這是 Google 的開源格式規範，旨在為編碼代理提供對設計系統（將令牌與設計理由合併在一個文件中）的持久化、結構化理解。適用於構建設計系統、在項目間移植樣式規則、生成具有一致品牌風格的 UI，或審計可訪問性/對比度時使用。

技能元數據


來源	捆綁（默認安裝）
路徑	`skills/creative/design-md`
版本	`1.0.0`
作者	Hermes Agent
許可證	MIT
標籤	`design`, `design-system`, `tokens`, `ui`, `accessibility`, `wcag`, `tailwind`, `dtcg`, `google`
相關技能	`popular-web-designs`, `excalidraw`, `architecture-diagram`

參考：完整 SKILL.md

信息

以下是 Hermes 在觸發此技能時加載的完整技能定義。這是技能激活時代理所看到的指令。

DESIGN.md 技能

DESIGN.md 是 Google 用於向編碼代理描述視覺身份的開放規範（Apache-2.0，google-labs-code/design.md）。單個文件包含：

YAML front matter —— 機器可讀的設計令牌（規範性值）
Markdown 正文 —— 人類可讀的設計理由，按標準章節組織

令牌提供精確的值。散文部分告訴代理為什麼存在這些值以及如何應用它們。CLI (npx @google/design.md) 用於檢查結構 + WCAG 對比度，比對版本以發現迴歸問題，並導出到 Tailwind 或 W3C DTCG JSON。

何時使用此技能

用戶請求 DESIGN.md 文件、設計令牌或設計規範
用戶希望在多個項目或工具之間保持 UI/品牌的一致性
用戶粘貼現有的 DESIGN.md 並要求對其進行 lint 檢查、比對、導出或擴展
用戶要求將樣式指南轉換為代理可消費的格式
用戶希望對其調色板進行對比度 / WCAG 可訪問性驗證

對於純粹的視覺靈感或佈局示例，請改用 popular-web-designs。此技能針對的是正式規範文件本身。

文件結構

---
version: alpha
name: Heritage
description: Architectural minimalism meets journalistic gravitas.
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
  lg: 16px
spacing:
  sm: 8px
  md: 16px
  lg: 24px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#FFFFFF"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.primary}"
---

## Overview

Architectural Minimalism meets Journalistic Gravitas...

## Colors

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.

## Typography

Public Sans for everything except small all-caps labels...

## Components

`button-primary` is the only high-emphasis action on a page...

令牌類型

類型	格式	示例
顏色 (Color)	`#` + 十六進制 (sRGB)	`"#1A1C1E"`
尺寸 (Dimension)	數字 + 單位 (`px`, `em`, `rem`)	`48px`, `-0.02em`
令牌引用 (Token reference)	`{path.to.token}`	`{colors.primary}`
排版 (Typography)	包含 `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation` 的對象	見上文

組件屬性白名單：backgroundColor, textColor, typography, rounded, padding, size, height, width。變體（hover, active, pressed）是獨立的組件條目，具有相關的鍵名 (button-primary-hover)，而非嵌套結構。

標準章節順序

章節是可選的，但存在的章節必須按此順序出現。重複的標題會導致文件被拒絕。

概述 (Overview)（別名：Brand & Style）
顏色 (Colors)
排版 (Typography)
佈局 (Layout)（別名：Layout & Spacing）
高程與深度 (Elevation & Depth)（別名：Elevation）
形狀 (Shapes)
組件 (Components)
建議與禁忌 (Do's and Don'ts)

未知章節會被保留，不會報錯。如果值類型有效，則接受未知的令牌名稱。未知的組件屬性會產生警告。

工作流：編寫新的 DESIGN.md

詢問用戶（或推斷）品牌基調、強調色和排版方向。如果他們提供了網站、圖片或氛圍參考，請將其轉換為上述令牌結構。
使用 write_file 在其項目根目錄中編寫 DESIGN.md。始終包含 name: 和 colors:；其他章節可選但鼓勵包含。
在 components: 部分中使用令牌引用 ({colors.primary})，而不是重新輸入十六進制值。這保持了調色板的單一數據源。
對其進行 Lint 檢查（見下文）。在返回結果之前，修復任何損壞的引用或 WCAG 失敗項。
如果用戶有現有項目，還要在該文件旁邊寫入 Tailwind 或 DTCG 導出文件 (tailwind.theme.json, tokens.json)。

工作流：Lint / Diff / Export

CLI 是 @google/design.md (Node)。使用 npx —— 無需全局安裝。

# Validate structure + token references + WCAG contrast
npx -y @google/design.md lint DESIGN.md

# Compare two versions, fail on regression (exit 1 = regression)
npx -y @google/design.md diff DESIGN.md DESIGN-v2.md

# Export to Tailwind theme JSON
npx -y @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json

# Export to W3C DTCG (Design Tokens Format Module) JSON
npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json

# Print the spec itself — useful when injecting into an agent prompt
npx -y @google/design.md spec --rules-only --format json

所有命令都接受 - 作為 stdin 輸入。lint 在出現錯誤時返回退出代碼 1。如果需要結構化地報告發現結果，請使用 --format json 標誌並解析輸出。

Lint 規則參考（7 條規則捕獲的內容）

broken-ref (錯誤) — {colors.missing} 指向不存在的令牌
duplicate-section (錯誤) — 相同的 ## Heading 出現兩次
invalid-color, invalid-dimension, invalid-typography (錯誤)
wcag-contrast (警告/信息) — 組件 textColor 與 backgroundColor 的比率相對於 WCAG AA (4.5:1) 和 AAA (7:1)
unknown-component-property (警告) — 不在上述白名單內

當用戶關心可訪問性時，請在總結中明確指出這一點 —— WCAG 發現結果是使用 CLI 的最重要原因。

常見陷阱

不要嵌套組件變體。 button-primary.hover 是錯誤的；應使用同級鍵 button-primary-hover。
十六進制顏色值必須是帶引號的字符串。 否則 YAML 會因 # 符號而出錯，或奇怪地截斷類似 #1A1C1E 的值。
負數維度值也需要加引號。 letterSpacing: -0.02em 會被解析為 YAML 流式集合 — 請寫作 letterSpacing: "-0.02em"。
章節順序是強制性的。 如果用戶提供的散文內容順序雜亂，在保存前請將其重新排序以匹配規範列表。
version: alpha 是當前規範版本（截至 2026 年 4 月）。該規範標記為 alpha 階段 — 請注意破壞性變更。
Token 引用通過點號路徑解析。 {colors.primary} 有效；{primary} 無效。

規範權威來源

倉庫：https://github.com/google-labs-code/design.md (Apache-2.0)
CLI：npm 上的 @google/design.md
生成的 DESIGN.md 文件的許可證：遵循用戶項目所使用的許可證；規範本身採用 Apache-2.0 許可證。

技能元數據​

參考：完整 SKILL.md​

DESIGN.md 技能

何時使用此技能​

文件結構​

令牌類型​

標準章節順序​

工作流：編寫新的 DESIGN.md​

工作流：Lint / Diff / Export​

Lint 規則參考（7 條規則捕獲的內容）​

常見陷阱​

規範權威來源​