🚀 安装与调用入口 >>>

安装

# 全局安装 CLI
npm install -g @google/design.md

# 也可以直接用 npx 一次性执行
npx @google/design.md lint DESIGN.md

在仓库里怎么放

your-project/
├─ DESIGN.md
├─ src/
└─ ...

• DESIGN.md
• 文件上半部分写 tokens，下半部分写设计原则，适合长期演进。
• agent 读取后，可以把“配色 / 字体 / 圆角 / 组件规则”持续带入生成结果。

最小可用文件

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
typography:
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
rounded:
  sm: 4px
spacing:
  md: 16px
---

## Overview

新闻感、克制、偏高对比；主色只给最重要动作。

起手调用方式

# 校验单个 DESIGN.md
npx @google/design.md lint DESIGN.md

# 对比两个版本
npx @google/design.md diff DESIGN.old.md DESIGN.md

# 导出到 Tailwind token
npx @google/design.md export --format tailwind DESIGN.md

# 输出规范文本给 agent / prompt 注入
npx @google/design.md spec

最小工作流

从 0 到 1

1. 先在项目根目录创建 `DESIGN.md`。
2. 用 YAML front matter 写颜色、字体、圆角、间距、组件 token。
3. 用 `##` 小节写设计意图、布局、组件规则、Do's and Don'ts。
4. 执行 `lint` 看结构、引用、对比度、章节顺序有没有问题。
5. 需要评审设计变更时，用 `diff` 比两个版本。
6. 需要喂给 Tailwind / token 管线时，用 `export` 导出。

最短闭环

# 1) 写文件
$EDITOR DESIGN.md

# 2) 先过 lint
npx @google/design.md lint DESIGN.md

# 3) 导出 token 给工程消费
npx @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json

适合什么时候上

• 想把“品牌感 + token + 组件规范”交给 AI 持续遵守
• 设计系统已经有雏形，但散落在 Figma、Tailwind、口头约定里
• 团队开始让 agent 生成页面，希望输出别再每次都换一套风格

🧭 高频 Recipes >>>

Recipe 1: 先验证文件有没有写坏

npx @google/design.md lint DESIGN.md

• 适合刚新建文件、刚改 token、刚补组件映射之后先做一次体检。
• 默认输出 JSON，方便被脚本、CI 或 agent 继续消费。

Recipe 2: 对比设计系统改动有没有回归

npx @google/design.md diff DESIGN.md DESIGN-v2.md

• 看 token 新增 / 删除 / 修改。
• 如果 after 版本出现更多 errors / warnings，会被视作 regression。

Recipe 3: 把 token 导出给前端工程

# 导出 Tailwind theme
npx @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json

# 导出 DTCG tokens
npx @google/design.md export --format dtcg DESIGN.md > tokens.json

• tailwind
• dtcg

Recipe 4: 把 spec 丢给 agent 当上下文

# 读 markdown 版规范
npx @google/design.md spec

# 只要规则表，机器处理更干净
npx @google/design.md spec --rules-only --format json

• 适合给 agent 提供“这个格式到底怎么算合法”的硬规则。
• 比自己口述更稳定，尤其适合写校验 / 修复 prompt。

🍳 文件结构速查 >>>

两层结构

---
# YAML front matter: 机器读的 tokens
---

## Overview
## Colors
## Typography
## Layout
## Elevation & Depth
## Shapes
## Components
## Do's and Don'ts

你可以这样理解

• design-tokens.json
• markdown body 像设计说明书，负责“语气、限制、使用原则”。
• 对 agent 来说，这和前端里“变量 + 文档注释”是一个类比，只是这里是设计系统版本。

canonical section 顺序

🧱 Token 速查 >>>

顶层 schema

version: alpha
name: Heritage
description: Optional
colors:
  primary: "#1A1C1E"
typography:
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
rounded:
  sm: 4px
spacing:
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.primary}"

token 类型

常见组别

组件与引用规则

组件定义

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"

合法组件属性

Quick Ref

• button-primary-hover
• components
• 未知 component property 会被接受，但给 warning，不是直接报错。

CLI 命令速查

命令总览

lint

npx @google/design.md lint DESIGN.md
npx @google/design.md lint --format json DESIGN.md
cat DESIGN.md | npx @google/design.md lint -

diff

npx @google/design.md diff DESIGN.md DESIGN-v2.md

export

npx @google/design.md export --format tailwind DESIGN.md
npx @google/design.md export --format dtcg DESIGN.md

spec

npx @google/design.md spec
npx @google/design.md spec --rules
npx @google/design.md spec --rules-only --format json

Lint 规则与分支决策

内置规则

常见判断

exit code

• lint 1 0：有 error 返回 ，否则
• diff 1：如果 after 版本出现 regression，返回

常见坑与排障

• DESIGN.md
• section-order
• {colors.primary} $primary
• components
• lineHeight fontSize padding rounded
• alpha 0.1.1