design-md-format

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DESIGN.md Format Skill

DESIGN.md 格式技能

Skill by ara.so — Design Skills collection.

DESIGN.md is a format specification for describing visual identity to coding agents. It combines machine-readable design tokens (YAML front matter) with human-readable design rationale (markdown prose), giving agents persistent, structured understanding of design systems.

由ara.so提供的技能 —— 设计技能合集。

DESIGN.md是一种用于向编码Agent描述视觉标识的格式规范。它将机器可读的设计令牌（YAML前置内容）与人类可读的设计原理（Markdown正文）相结合，让Agent能够持久、结构化地理解设计系统。

Installation

安装

bash

npm install @google/design.md

For direct CLI usage without installation:

bash

npx @google/design.md lint DESIGN.md

Windows note: When using the CLI in

package.json

scripts on Windows, use the

designmd

alias instead of

design.md

to avoid file association issues:

json

{
  "scripts": {
    "design:lint": "designmd lint DESIGN.md"
  }
}

bash

npm install @google/design.md

无需安装即可直接使用CLI：

bash

npx @google/design.md lint DESIGN.md

Windows 注意事项：在Windows系统的

package.json

脚本中使用CLI时，请使用

designmd

别名代替

design.md

，以避免文件关联问题：

json

{
  "scripts": {
    "design:lint": "designmd lint DESIGN.md"
  }
}

File Structure

文件结构

A DESIGN.md file has two layers:

YAML front matter — Machine-readable tokens (colors, typography, spacing, etc.)
Markdown body — Human-readable rationale organized into specific sections

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#ffffff"
    rounded: "{rounded.sm}"
    padding: 12px
---

DESIGN.md文件包含两层内容：

YAML前置内容 —— 机器可读的设计令牌（颜色、排版、间距等）
Markdown正文 —— 按特定章节组织的人类可读设计原理

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#ffffff"
    rounded: "{rounded.sm}"
    padding: 12px
---

Overview

概述

Architectural Minimalism meets Journalistic Gravitas.

建筑极简主义与新闻庄重感的融合。

Colors

颜色

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

undefined

主色 (#1A1C1E)：用于标题和核心文本的深墨色。
强调色 (#B8422E)：「波士顿黏土色」—— 交互行为驱动色。

undefined

Creating a DESIGN.md File

创建DESIGN.md文件

Complete Token Schema

完整令牌 schema

yaml

version: <string>          # optional, current: "alpha"
name: <string>             # required
description: <string>      # optional
colors:
  <token-name>: <Color>    # "#" + hex (sRGB)
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <property>: <value | token reference>

yaml

version: <string>          # 可选，当前版本："alpha"
name: <string>             # 必填
description: <string>      # 可选
colors:
  <token-name>: <Color>    # "#" + 十六进制色值（sRGB）
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <property>: <value | token reference>

Token Types

令牌类型

Color: Hex format with

prefix

yaml

colors:
  primary: "#1A1C1E"
  accent: "#B8422E"
  on-primary: "#FFFFFF"

Typography: Object with font properties

yaml

typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
    fontWeight: 700
    lineHeight: 1.2
    letterSpacing: -0.02em
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.5

Dimension: Number + unit (

px

em

rem

)

yaml

rounded:
  sm: 4px
  md: 8px
  lg: 16px
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px

Token Reference:

{path.to.token}

yaml

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"

Color：带

前缀的十六进制格式

yaml

colors:
  primary: "#1A1C1E"
  accent: "#B8422E"
  on-primary: "#FFFFFF"

Typography：包含字体属性的对象

yaml

typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
    fontWeight: 700
    lineHeight: 1.2
    letterSpacing: -0.02em
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.5

Dimension：数字 + 单位（

px

em

rem

）

yaml

rounded:
  sm: 4px
  md: 8px
  lg: 16px
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px

Token Reference：

{path.to.token}

yaml

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"

Component Tokens

组件令牌

Valid component properties:

```
backgroundColor
```
```
textColor
```
```
typography
```
```
rounded
```
```
padding
```
```
size
```
```
height
```
```
width
```

yaml

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#ffffff"
    typography: "{typography.label-caps}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"
  card:
    backgroundColor: "{colors.neutral}"
    rounded: "{rounded.md}"
    padding: "{spacing.md}"

有效的组件属性：

```
backgroundColor
```
```
textColor
```
```
typography
```
```
rounded
```
```
padding
```
```
size
```
```
height
```
```
width
```

yaml

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#ffffff"
    typography: "{typography.label-caps}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"
  card:
    backgroundColor: "{colors.neutral}"
    rounded: "{rounded.md}"
    padding: "{spacing.md}"

Section Order

章节顺序

Markdown sections use

##

headings and must appear in this order (all optional):

Overview (or "Brand & Style")
Colors
Typography
Layout (or "Layout & Spacing")
Elevation & Depth (or "Elevation")
Shapes
Components
Do's and Don'ts

undefined

Markdown章节使用

##

标题，必须按以下顺序排列（所有章节均为可选）：

概述（或「品牌与风格」）
颜色
排版
布局（或「布局与间距」）
层级与深度（或「层级」）
形状
组件
注意事项

undefined

Overview

概述

Brief description of the design philosophy.

设计理念的简要描述。

Colors

颜色

Rationale for each color token and when to use it.

Primary (#1A1C1E): Deep ink for headlines
Tertiary (#B8422E): Interaction driver

每个颜色令牌的设计原理及使用场景说明。

主色 (#1A1C1E)：用于标题的深墨色
强调色 (#B8422E)：交互行为驱动色

Typography

排版

Font selection rationale and hierarchy guidance.

字体选择依据及层级设计指南。

Components

组件

How to apply component tokens in context.

undefined

组件令牌在实际场景中的应用方式。

undefined

CLI Commands

CLI 命令

Lint

Lint（校验）

Validate a DESIGN.md file for structural correctness, broken references, and WCAG contrast issues:

bash

undefined

验证DESIGN.md文件的结构正确性、令牌引用有效性以及WCAG对比度问题：

bash

undefined

Validate from file

从文件验证

npx @google/design.md lint DESIGN.md

From stdin

从标准输入验证

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

Specify output format (only json currently)

指定输出格式（目前仅支持json）

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


**Output**: JSON with findings array and summary
```json
{
  "findings": [
    {
      "severity": "warning",
      "path": "components.button-primary",
      "message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "info": 1 }
}

Exit codes:

```
0
```
: No errors
```
1
```
: Errors found

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


**输出**：包含检查结果数组和摘要的JSON
```json
{
  "findings": [
    {
      "severity": "warning",
      "path": "components.button-primary",
      "message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "info": 1 }
}

退出码：

```
0
```
：无错误
```
1
```
：检测到错误

Diff

Diff（对比）

Compare two DESIGN.md versions to detect token changes and regressions:

bash

npx @google/design.md diff DESIGN.md DESIGN-v2.md
npx @google/design.md diff --format json old.md new.md

Output: Token-level changes

json

{
  "tokens": {
    "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
    "typography": { "added": [], "removed": [], "modified": [] }
  },
  "regression": false
}

Exit codes:

```
0
```
: No regressions
```
1
```
: Regressions detected (more errors/warnings in "after")

对比两个DESIGN.md版本，检测令牌变化和回归问题：

bash

npx @google/design.md diff DESIGN.md DESIGN-v2.md
npx @google/design.md diff --format json old.md new.md

输出：令牌级别的变化

json

{
  "tokens": {
    "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
    "typography": { "added": [], "removed": [], "modified": [] }
  },
  "regression": false
}

退出码：

```
0
```
：无回归问题
```
1
```
：检测到回归问题（新版本存在更多错误/警告）

Export

Export（导出）

Convert DESIGN.md tokens to other formats:

bash

undefined

将DESIGN.md令牌转换为其他格式：

bash

undefined

Tailwind v3 JSON config

Tailwind v3 JSON 配置

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

npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json npx @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json # 别名

Tailwind v4 CSS theme

Tailwind v4 CSS 主题

npx @google/design.md export --format css-tailwind DESIGN.md > theme.css

W3C Design Tokens Format (DTCG)

W3C 设计令牌格式（DTCG）

npx @google/design.md export --format dtcg DESIGN.md > tokens.json

From stdin

从标准输入导出

cat DESIGN.md | npx @google/design.md export --format dtcg - > tokens.json


**Tailwind v3 JSON output** (`json-tailwind`):
```json
{
  "colors": {
    "primary": "#1A1C1E",
    "secondary": "#6C7278",
    "tertiary": "#B8422E"
  },
  "fontFamily": {
    "sans": ["Public Sans", "sans-serif"]
  },
  "fontSize": {
    "h1": "3rem",
    "body-md": "1rem"
  },
  "borderRadius": {
    "sm": "4px",
    "md": "8px"
  },
  "spacing": {
    "sm": "8px",
    "md": "16px"
  }
}

Tailwind v4 CSS output (

css-tailwind

css

@theme {
  --color-primary: #1A1C1E;
  --color-secondary: #6C7278;
  --color-tertiary: #B8422E;
  --font-sans: "Public Sans", sans-serif;
  --text-h1: 3rem;
  --text-body-md: 1rem;
  --radius-sm: 4px;
  --radius-md: 8px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
}

cat DESIGN.md | npx @google/design.md export --format dtcg - > tokens.json


**Tailwind v3 JSON 输出**（`json-tailwind`）：
```json
{
  "colors": {
    "primary": "#1A1C1E",
    "secondary": "#6C7278",
    "tertiary": "#B8422E"
  },
  "fontFamily": {
    "sans": ["Public Sans", "sans-serif"]
  },
  "fontSize": {
    "h1": "3rem",
    "body-md": "1rem"
  },
  "borderRadius": {
    "sm": "4px",
    "md": "8px"
  },
  "spacing": {
    "sm": "8px",
    "md": "16px"
  }
}

Tailwind v4 CSS 输出（

css-tailwind

）：

css

@theme {
  --color-primary: #1A1C1E;
  --color-secondary: #6C7278;
  --color-tertiary: #B8422E;
  --font-sans: "Public Sans", sans-serif;
  --text-h1: 3rem;
  --text-body-md: 1rem;
  --radius-sm: 4px;
  --radius-md: 8px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
}

Spec

Spec（规范）

Output the DESIGN.md specification (useful for agent prompts):

bash

undefined

输出DESIGN.md规范（适用于Agent提示词）：

bash

undefined

Full spec

完整规范

npx @google/design.md spec

Spec + linting rules

规范 + 校验规则

npx @google/design.md spec --rules

Only linting rules

仅输出校验规则

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

JSON format

JSON格式

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

undefined

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

undefined

Programmatic API

编程式API

Linting

校验

typescript

import { lint } from '@google/design.md/linter';

const markdownString = `
---
name: MyDesign
colors:
  primary: "#1A1C1E"
components:
  button:
    backgroundColor: "{colors.primary}"
    textColor: "#ffffff"
---

typescript

import { lint } from '@google/design.md/linter';

const markdownString = `
---
name: MyDesign
colors:
  primary: "#1A1C1E"
components:
  button:
    backgroundColor: "{colors.primary}"
    textColor: "#ffffff"
---

Overview

概述

Modern design system. `;

const report = lint(markdownString);

console.log(report.findings); // [ // { // severity: 'warning', // path: 'components.button', // message: 'textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA.' // } // ]

console.log(report.summary); // { errors: 0, warnings: 1, info: 1 }

console.log(report.designSystem); // Parsed DesignSystemState object

undefined

现代设计系统。 `;

const report = lint(markdownString);

console.log(report.summary); // { errors: 0, warnings: 1, info: 1 }

console.log(report.designSystem); // 解析后的DesignSystemState对象

undefined

Parsing and Validation

解析与验证

typescript

import { lint, type Finding } from '@google/design.md/linter';

function validateDesignFile(content: string): boolean {
  const report = lint(content);
  
  const hasErrors = report.findings.some((f: Finding) => f.severity === 'error');
  
  if (hasErrors) {
    console.error('Validation failed:');
    report.findings
      .filter((f: Finding) => f.severity === 'error')
      .forEach((f: Finding) => console.error(`  ${f.path}: ${f.message}`));
    return false;
  }
  
  return true;
}

typescript

import { lint, type Finding } from '@google/design.md/linter';

function validateDesignFile(content: string): boolean {
  const report = lint(content);
  
  const hasErrors = report.findings.some((f: Finding) => f.severity === 'error');
  
  if (hasErrors) {
    console.error('验证失败：');
    report.findings
      .filter((f: Finding) => f.severity === 'error')
      .forEach((f: Finding) => console.error(`  ${f.path}: ${f.message}`));
    return false;
  }
  
  return true;
}

Common Patterns

常见模式

Creating a Design System from Scratch

从零开始创建设计系统

---
version: alpha
name: ProductName
description: Modern SaaS design system
colors:
  primary: "#2563eb"
  secondary: "#64748b"
  tertiary: "#0ea5e9"
  neutral: "#f8fafc"
  on-primary: "#ffffff"
  on-tertiary: "#ffffff"
typography:
  h1:
    fontFamily: Inter
    fontSize: 2.5rem
    fontWeight: 700
    lineHeight: 1.2
  h2:
    fontFamily: Inter
    fontSize: 2rem
    fontWeight: 600
    lineHeight: 1.3
  body:
    fontFamily: Inter
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.5
  label:
    fontFamily: Inter
    fontSize: 0.875rem
    fontWeight: 500
rounded:
  sm: 4px
  md: 8px
  lg: 12px
  full: 9999px
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
  xl: 32px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.label}"
    rounded: "{rounded.md}"
    padding: 12px 24px
  button-primary-hover:
    backgroundColor: "#1d4ed8"
  card:
    backgroundColor: "{colors.neutral}"
    rounded: "{rounded.lg}"
    padding: "{spacing.lg}"
  input:
    backgroundColor: "{colors.neutral}"
    textColor: "{colors.primary}"
    rounded: "{rounded.sm}"
    padding: "{spacing.sm}"
---

---
version: alpha
name: ProductName
description: 现代SaaS设计系统
colors:
  primary: "#2563eb"
  secondary: "#64748b"
  tertiary: "#0ea5e9"
  neutral: "#f8fafc"
  on-primary: "#ffffff"
  on-tertiary: "#ffffff"
typography:
  h1:
    fontFamily: Inter
    fontSize: 2.5rem
    fontWeight: 700
    lineHeight: 1.2
  h2:
    fontFamily: Inter
    fontSize: 2rem
    fontWeight: 600
    lineHeight: 1.3
  body:
    fontFamily: Inter
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.5
  label:
    fontFamily: Inter
    fontSize: 0.875rem
    fontWeight: 500
rounded:
  sm: 4px
  md: 8px
  lg: 12px
  full: 9999px
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
  xl: 32px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.label}"
    rounded: "{rounded.md}"
    padding: 12px 24px
  button-primary-hover:
    backgroundColor: "#1d4ed8"
  card:
    backgroundColor: "{colors.neutral}"
    rounded: "{rounded.lg}"
    padding: "{spacing.lg}"
  input:
    backgroundColor: "{colors.neutral}"
    textColor: "{colors.primary}"
    rounded: "{rounded.sm}"
    padding: "{spacing.sm}"
---

Overview

概述

Clean, modern SaaS interface prioritizing readability and trust.

简洁现代的SaaS界面，优先保证可读性与信任感。

Colors

颜色

Primary (#2563eb): Brand blue for primary actions
Secondary (#64748b): Slate for secondary text and borders
Tertiary (#0ea5e9): Sky blue for links and highlights
Neutral (#f8fafc): Near-white background

主色 (#2563eb)：品牌蓝色，用于主要操作
辅助色 (#64748b)：石板色，用于次要文本和边框
强调色 (#0ea5e9)：天蓝色，用于链接和高亮
中性色 (#f8fafc)：近白色背景

Typography

排版

Single font family (Inter) for consistency. Weight and size establish hierarchy.

使用单一字体家族（Inter）保证一致性，通过字重和字号建立层级。

Components

组件

All interactive elements use

button-primary

tokens. Cards use

card

tokens.

undefined

所有交互元素均使用

button-primary

令牌，卡片使用

card

令牌。

undefined

Integrating with Tailwind

与Tailwind集成

After exporting to Tailwind format:

bash

npx @google/design.md export --format json-tailwind DESIGN.md > design-tokens.json

Tailwind v3 config:

javascript

// tailwind.config.js
const designTokens = require('./design-tokens.json');

module.exports = {
  theme: {
    extend: designTokens
  }
};

Tailwind v4 with CSS:

bash

npx @google/design.md export --format css-tailwind DESIGN.md > src/theme.css

css

/* src/styles.css */
@import "./theme.css";
@import "tailwindcss";

导出为Tailwind格式后：

bash

npx @google/design.md export --format json-tailwind DESIGN.md > design-tokens.json

Tailwind v3 配置：

javascript

// tailwind.config.js
const designTokens = require('./design-tokens.json');

module.exports = {
  theme: {
    extend: designTokens
  }
};

Tailwind v4 CSS集成：

bash

npx @google/design.md export --format css-tailwind DESIGN.md > src/theme.css

css

/* src/styles.css */
@import "./theme.css";
@import "tailwindcss";

Token References Pattern

令牌引用模式

Always reference tokens rather than duplicating values:

yaml

undefined

始终引用令牌而非重复值：

yaml

undefined

✅ Good - uses references

✅ 推荐 - 使用引用

components: button-primary: backgroundColor: "{colors.primary}" textColor: "{colors.on-primary}" rounded: "{rounded.md}" button-secondary: backgroundColor: "{colors.secondary}" textColor: "{colors.on-primary}" rounded: "{rounded.md}"

❌ Bad - duplicates values

❌ 不推荐 - 重复值

components: button-primary: backgroundColor: "#2563eb" textColor: "#ffffff" rounded: 8px button-secondary: backgroundColor: "#64748b" textColor: "#ffffff" rounded: 8px

undefined

components: button-primary: backgroundColor: "#2563eb" textColor: "#ffffff" rounded: 8px button-secondary: backgroundColor: "#64748b" textColor: "#ffffff" rounded: 8px

undefined

Variant Pattern for Component States

组件状态变体模式

yaml

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
    padding: 12px 24px
  button-primary-hover:
    backgroundColor: "#1d4ed8"
  button-primary-active:
    backgroundColor: "#1e40af"
  button-primary-disabled:
    backgroundColor: "{colors.secondary}"
    textColor: "#94a3b8"

yaml

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
    padding: 12px 24px
  button-primary-hover:
    backgroundColor: "#1d4ed8"
  button-primary-active:
    backgroundColor: "#1e40af"
  button-primary-disabled:
    backgroundColor: "{colors.secondary}"
    textColor: "#94a3b8"

Linting Rules Reference

校验规则参考

Rule	Severity	Description
`broken-ref`	error	Token reference doesn't resolve (e.g., `{colors.missing}` )
`missing-primary`	warning	No `primary` color defined — agents will auto-generate
`contrast-ratio`	warning	Component backgroundColor/textColor below WCAG AA (4.5:1)
`orphaned-tokens`	warning	Color token defined but never referenced
`token-summary`	info	Summary of token counts per section
`missing-sections`	info	Optional sections absent when other tokens exist
`missing-typography`	warning	Colors defined but no typography tokens
`section-order`	warning	Sections appear out of canonical order

规则	严重程度	描述
`broken-ref`	error	令牌引用无法解析（例如： `{colors.missing}` ）
`missing-primary`	warning	未定义 `primary` 颜色 —— Agent将自动生成
`contrast-ratio`	warning	组件的backgroundColor/textColor对比度未达到WCAG AA标准（4.5:1）
`orphaned-tokens`	warning	颜色令牌已定义但从未被引用
`token-summary`	info	各章节令牌数量的摘要
`missing-sections`	info	当存在其他令牌时，缺少可选章节
`missing-typography`	warning	已定义颜色但未定义排版令牌
`section-order`	warning	章节未按标准顺序排列

Troubleshooting

故障排除

npm error ENOVERSIONS

npm error ENOVERSIONS

Problem:

No versions available for @google/design.md

Cause: npm not querying public registry (custom registry in

.npmrc

, corporate mirror, misconfigured scope)

Solution:

bash

undefined

问题：

No versions available for @google/design.md

原因：npm未查询公共注册表（

.npmrc

中配置了自定义注册表、企业镜像或作用域配置错误）

解决方案：

bash

undefined

Check current registry

检查当前注册表

npm config get registry

Should be: https://registry.npmjs.org/

应为：https://registry.npmjs.org/

Clear cache and retry

清除缓存并重试

npm cache clean --force npm install @google/design.md

undefined

npm cache clean --force npm install @google/design.md

undefined

Broken Token References

令牌引用失效

Problem:

broken-ref

error for

{colors.accent}

Cause: Token doesn't exist in YAML front matter

Solution:

yaml

colors:
  accent: "#0ea5e9"  # Add the missing token

Or update the reference:

yaml

components:
  button:
    backgroundColor: "{colors.primary}"  # Use existing token

问题：

broken-ref

错误提示

{colors.accent}

原因：YAML前置内容中不存在该令牌

解决方案：

yaml

colors:
  accent: "#0ea5e9"  # 添加缺失的令牌

或更新引用：

yaml

components:
  button:
    backgroundColor: "{colors.primary}"  # 使用已存在的令牌

WCAG Contrast Failures

WCAG对比度不达标

Problem:

contrast-ratio

warning for component

Solution: Adjust colors to meet 4.5:1 minimum:

yaml

undefined

问题：组件出现

contrast-ratio

警告

解决方案：调整颜色以满足4.5:1的最低标准：

yaml

undefined

Before (low contrast)

调整前（对比度低）

components: button: backgroundColor: "#e0e0e0" textColor: "#ffffff"

After (high contrast)

调整后（对比度高）

components: button: backgroundColor: "#1A1C1E" textColor: "#ffffff"


Or define explicit on-* colors:
```yaml
colors:
  primary: "#2563eb"
  on-primary: "#ffffff"  # Guaranteed high contrast
components:
  button:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"

components: button: backgroundColor: "#1A1C1E" textColor: "#ffffff"


或定义明确的on-*颜色：
```yaml
colors:
  primary: "#2563eb"
  on-primary: "#ffffff"  # 确保高对比度
components:
  button:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"

Section Order Warnings

章节顺序警告

Problem:

section-order

warning

Cause: Sections out of canonical order

Solution: Reorder markdown sections:

undefined

问题：

section-order

警告

原因：章节未按标准顺序排列

解决方案：重新排列Markdown章节：

undefined

Overview

概述

...

Colors

颜色

...

Typography

排版

...

Components

组件

...

undefined

...

undefined

Windows CLI Issues

Windows CLI问题

Problem: CLI not executing in

package.json

scripts on Windows

Solution: Use

designmd

alias instead of

design.md

json

{
  "scripts": {
    "lint": "designmd lint DESIGN.md",
    "export": "designmd export --format tailwind DESIGN.md > tokens.json"
  }
}

问题：Windows系统中

package.json

脚本无法执行CLI

解决方案：使用

designmd

别名代替

design.md

：

json

{
  "scripts": {
    "lint": "designmd lint DESIGN.md",
    "export": "designmd export --format tailwind DESIGN.md > tokens.json"
  }
}

Best Practices

最佳实践

Always define
primary
color — Prevents agent auto-generation
Use token references — Single source of truth for design changes
Include typography early — Prevents agents from using default fonts
Write prose rationale — Explains why tokens exist and how to apply them
Validate before committing — Run
```
lint
```
in CI/CD pipeline
Version your DESIGN.md — Track design evolution with
```
diff
```
Define component variants explicitly —
```
button-primary-hover
```
, not just
```
button-primary
```
Check contrast ratios — Linter catches WCAG issues automatically

始终定义
primary
颜色 —— 避免Agent自动生成
使用令牌引用 —— 设计变更的单一数据源
尽早定义排版 —— 避免Agent使用默认字体
编写设计原理正文 —— 解释令牌存在的原因及应用方式
提交前进行验证 —— 在CI/CD流水线中运行
```
lint
```
为DESIGN.md版本化 —— 使用
```
diff
```
跟踪设计演进
明确定义组件变体 —— 例如
```
button-primary-hover
```
，而非仅
```
button-primary
```
检查对比度 —— 校验器会自动检测WCAG问题

Integration Examples

集成示例

CI/CD Validation

CI/CD验证

yaml

undefined

yaml

undefined

.github/workflows/design.yml

name: Validate Design System on: [push, pull_request] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: actions/setup-node@v3 - run: npx @google/design.md lint DESIGN.md

undefined

name: 验证设计系统 on: [push, pull_request] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: actions/setup-node@v3 - run: npx @google/design.md lint DESIGN.md

undefined

Pre-commit Hook

提交前钩子

json

{
  "husky": {
    "hooks": {
      "pre-commit": "npx @google/design.md lint DESIGN.md"
    }
  }
}

json

{
  "husky": {
    "hooks": {
      "pre-commit": "npx @google/design.md lint DESIGN.md"
    }
  }
}

Build-time Token Export

构建时令牌导出

json

{
  "scripts": {
    "prebuild": "designmd export --format tailwind DESIGN.md > src/design-tokens.json",
    "build": "vite build"
  }
}

json

{
  "scripts": {
    "prebuild": "designmd export --format tailwind DESIGN.md > src/design-tokens.json",
    "build": "vite build"
  }
}