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 条规则捕获的内容）​

常见陷阱​

规范权威来源​