我们要解决的问题是如何定义和管理设计系统。为了开始这个过程，我们需要了解什么是 DESIGN.md。DESIGN.md 是一种用于描述视觉身份的格式规范，它通过 YAML 前置内容和 Markdown 文档，提供给编码代理一个持久、结构化的设计系统理解。

首先，我们需要确保我们有一个基本的环境来开始使用 DESIGN.md。由于 DESIGN.md 是一个 npm 包，所以我们需要确保我们的 npm 环境正常工作。如果你遇到 ENOVERSIONS 错误，可能是因为你的 npm 配置有问题，可以通过运行以下命令来检查你的 registry：

npm config get registry

如果你的 registry 不是 https://registry.npmjs.org/，你可能需要调整你的配置。

DESIGN.md 文件由两部分组成：可选的 YAML 前置内容和 Markdown 主体。YAML 前置内容包含机器可读的设计 tokens，而 Markdown 主体提供人类可读的设计理由和指导。设计 tokens 是规范值，而 Markdown 文本提供了如何应用这些值的上下文。

例如，一个 DESIGN.md 文件可能包含以下 YAML 前置内容：

---
primary: "#34A85A"
secondary: "#FFC107"
---

接着是 Markdown 主体：

# 颜色系统
我们使用两种主要颜色：`primary` 和 `secondary`。
`primary` 颜色用于主要按钮和标题，而 `secondary` 颜色用于次要按钮和文字。

通过这种方式，DESIGN.md 文件提供了一个清晰、结构化的设计系统定义，可以被人类和机器都理解和遵循。

本章小结

• DESIGN.md 是一种用于描述视觉身份的格式规范
• DESIGN.md 文件由 YAML 前置内容和 Markdown 主体组成
• YAML 前置内容包含机器可读的设计 tokens，而 Markdown 主体提供人类可读的设计理由和指导

创建和验证 DESIGN.md 文件

现在我们已经了解了 DESIGN.md 的基本概念，我们可以开始创建和验证自己的 DESIGN.md 文件了。首先，我们需要确保我们已经安装了 @google/design.md 包。

npm install @google/design.md

如果你遇到 ENOVERSIONS 错误，记得检查你的 npm 配置，确保你使用的是公共 registry：

npm config get registry

如果不是，调整你的配置并重试安装。

创建 DESIGN.md 文件

让我们创建一个简单的 DESIGN.md 文件。首先，我们需要添加 YAML 前置内容：

---
primary: "#34A85A"
secondary: "#FFC107"
---

接着，我们添加 Markdown 主体：

# 颜色系统
我们使用两种主要颜色：`primary` 和 `secondary`。
`primary` 颜色用于主要按钮和标题，而 `secondary` 颜色用于次要按钮和文字。

保存文件为 DESIGN.md。

验证 DESIGN.md 文件

我们可以使用 designmd 命令来验证我们的 DESIGN.md 文件：

npx designmd lint DESIGN.md

如果文件格式正确，命令将输出 JSON 格式的结果。如果有错误，命令将报告错误信息。

注意事项：在 Windows 系统上，直接调用 design.md 命令可能会出现问题，建议使用 designmd 别名。

// package.json
{
  "scripts": {
    "design:lint": "designmd lint DESIGN.md"
  }
}

本章小结

• 安装 @google/design.md 包
• 创建 DESIGN.md 文件，包含 YAML 前置内容和 Markdown 主体
• 使用 designmd 命令验证 DESIGN.md 文件格式
• 注意 Windows 系统上的命令调用问题，使用 designmd 别名解决

理解 DESIGN.md 格式规范

DESIGN.md 文件由两部分组成：可选的 YAML 前置内容和 Markdown 主体。我们先来看 YAML 前置内容：

---
primary: "#3498db"
secondary: "#f1c40f"
---

这个 YAML 块定义了两个颜色变量：primary 和 secondary。这些变量可以在 Markdown 主体中使用。

接着，我们来看 Markdown 主体：

# 颜色规范
我们使用两种主要颜色：`primary` 和 `secondary`。
`primary` 颜色用于主要按钮和标题，而 `secondary` 颜色用于次要按钮和文字。

在 Markdown 主体中，我们使用了 primary 和 secondary 变量来描述颜色规范。

注意事项：YAML 前置内容和 Markdown 主体之间的对齐很重要。YAML 块必须位于文件的开头，后面跟着一个空行，然后是 Markdown 主体。

我们可以使用表格来总结 DESIGN.md 文件的结构：

部分	描述
YAML 前置内容	定义机器可读的设计 tokens
Markdown 主体	提供人类可读的设计理念和指导

实用技巧：在编辑 DESIGN.md 文件时，使用 YAML 语法高亮和 Markdown 预览功能，可以帮助你更好地理解文件的结构和内容。

如果你遇到 DESIGN.md 文件格式错误，可以使用 designmd 命令来诊断问题：

npx designmd lint DESIGN.md

这将帮助你快速找到并修复错误。

本章小结

• DESIGN.md 文件由 YAML 前置内容和 Markdown 主体组成
• YAML 前置内容定义机器可读的设计 tokens
• Markdown 主体提供人类可读的设计理念和指导
• 使用 designmd 命令来诊断 DESIGN.md 文件格式错误

使用 DESIGN.md CLI 工具可以帮助你更高效地管理和维护你的设计系统。首先，确保你已经安装了 @google/design.md 包：

npm install -g @google/design.md

如果你遇到安装错误，检查你的 npm 配置：

npm config get registry

确保注册表地址为 https://registry.npmjs.org/。如果不是，修改配置后重试安装。

安装完成后，你可以使用 designmd 命令来lint你的 DESIGN.md 文件：

designmd lint DESIGN.md

这将帮助你发现并修复 DESIGN.md 文件中的格式错误。

你也可以使用 designmd 命令来比较不同版本的设计系统：

designmd diff DESIGN.md DESIGN-v2.md

这将输出两个文件之间的差异。

在使用 designmd 命令时，你可以指定文件路径或使用 - 来表示标准输入。输出默认为 JSON 格式。

如果你在 Windows 上使用 designmd 命令，注意使用 designmd 别名代替 design.md，以避免文件关联问题：

// package.json
{
  "scripts": {
    "design:lint": "designmd lint DESIGN.md"
  }
}

记住一点：在使用 DESIGN.md CLI 工具时，保持你的 DESIGN.md 文件格式正确和最新是非常重要的。

实用技巧：使用 designmd 命令来自动化你的设计系统管理任务，可以帮助你提高效率和减少错误。

如果你遇到 designmd 命令错误，可以检查错误消息以确定问题所在。常见错误包括文件路径错误、格式错误和注册表配置错误。

本章小结

• 安装 @google/design.md 包以使用 DESIGN.md CLI 工具
• 使用 designmd 命令来 lint 和比较 DESIGN.md 文件
• 指定文件路径或使用 - 来表示标准输入
• 输出默认为 JSON 格式
• 在 Windows 上使用 designmd 别名代替 design.md 以避免文件关联问题

比较不同版本的设计系统是设计系统管理的一个重要方面。我们先来看看如何使用 designmd 命令来比较两个版本的设计系统。

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

这条命令会比较 DESIGN.md 和 DESIGN-v2.md 两个文件，输出一个 JSON 格式的报告，报告中包括了两个版本之间的差异。

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

从这个报告中，我们可以看到 DESIGN-v2.md 中添加了一个新的颜色 token accent，并且修改了 tertiary 颜色的值。

如果你遇到比较过程中出现错误，可以检查错误消息以确定问题所在。常见错误包括文件路径错误、格式错误和注册表配置错误。

记住一点：在比较不同版本的设计系统时，保持你的 DESIGN.md 文件格式正确和最新是非常重要的。

实用技巧：使用 designmd 命令来自动化你的设计系统管理任务，可以帮助你提高效率和减少错误。

下面是一个比较不同版本的设计系统的例子：

假设我们有两个版本的设计系统，DESIGN.md 和 DESIGN-v2.md，我们可以使用 designmd 命令来比较它们：

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

输出的报告中会显示两个版本之间的差异，我们可以根据这个报告来确定哪些部分需要更新或修改。

本章小结

• 使用 designmd 命令来比较不同版本的设计系统
• 输出的报告中包括了两个版本之间的差异
• 可以使用 designmd 命令来自动化你的设计系统管理任务
• 保持你的 DESIGN.md 文件格式正确和最新是非常重要的
• 可以使用 designmd 命令来比较不同版本的设计系统，并输出一个 JSON 格式的报告。

管理和维护你的设计系统需要持续的关注和更新。我们先从检查 DESIGN.md 文件的格式和内容开始，确保它符合 DESIGN.md 规范。

npx @google/design.md lint DESIGN.md

这条命令会输出一个 JSON 格式的报告，包含文件中的错误、警告和信息。检查这个报告可以帮助你找出需要更新或修改的地方。

接着，我们需要更新 DESIGN.md 文件以反映设计系统的变化。例如，如果我们要添加一个新的颜色 token，我们可以在 YAML 前置内容中添加一个新的颜色定义：

colors:
  accent: "#3498db"

然后，我们需要重新运行 lint 命令来验证更新后的文件：

npx @google/design.md lint DESIGN.md

如果更新后的文件没有错误或警告，我们就可以将其作为新的设计系统版本。

在管理和维护设计系统时，比较不同版本的设计系统也是非常重要的。我们可以使用 diff 命令来比较两个版本的 DESIGN.md 文件：

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

这条命令会输出一个 JSON 格式的报告，包含两个版本之间的差异。检查这个报告可以帮助你确定哪些部分需要更新或修改。

记住一点：在管理和维护设计系统时，保持 DESIGN.md 文件格式正确和最新是非常重要的。同时，使用 designmd 命令来自动化你的设计系统管理任务可以帮助你提高效率和减少错误。

本章小结

• 使用 designmd 命令来检查 DESIGN.md 文件的格式和内容
• 更新 DESIGN.md 文件以反映设计系统的变化
• 使用 diff 命令来比较不同版本的设计系统
• 保持 DESIGN.md 文件格式正确和最新是非常重要的
• 使用 designmd 命令来自动化你的设计系统管理任务可以帮助你提高效率和减少错误。

高级主题：使用 DESIGN.md 与其他工具集成

在前面的章节中，我们已经学习了如何创建和管理 DESIGN.md 文件。现在，我们将探讨如何将 DESIGN.md 与其他工具集成，以进一步提高设计系统的管理效率。

首先，我们需要了解 DESIGN.md 文件的格式规范。DESIGN.md 文件包含两个部分：可选的 YAML 前置内容和 Markdown 文档体。YAML 前置内容包含机器可读的设计令牌，而 Markdown 文档体提供人类可读的设计理由和指导。

集成 DESIGN.md 与 npm

要将 DESIGN.md 与 npm 集成，我们需要将 @google/design.md 包安装到我们的项目中。我们可以使用以下命令来安装：

npm install @google/design.md

安装完成后，我们可以使用 designmd 命令来运行 DESIGN.md 相关的任务。

解决 npm 安装错误

在安装 @google/design.md 包时，我们可能会遇到 ENOVERSIONS 错误。这通常是由于 npm 配置问题引起的。我们可以使用以下命令来检查我们的有效注册表：

npm config get registry

如果注册表配置不正确，我们可以使用以下命令来修复：

npm config set registry https://registry.npmjs.org/

然后，我们可以重试安装。

在 package.json 中使用 designmd

我们可以在 package.json 中添加一个脚本来运行 designmd 命令。例如：

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

在 Windows 平台上，我们需要使用 designmd 别名代替 design.md，以避免文件关联问题。

使用 designmd 命令

designmd 命令提供了多种选项来管理我们的 DESIGN.md 文件。我们可以使用以下命令来查看所有可用选项：

npx designmd --help

常用的选项包括 lint、diff 和 validate。

集成 DESIGN.md 与其他设计工具

DESIGN.md 文件可以与其他设计工具集成，以提供更全面的设计系统管理解决方案。例如，我们可以使用 DESIGN.md 文件来生成设计规范文档，或将其与设计工具如 Sketch 或 Figma 集成。

本章小结

• 了解 DESIGN.md 文件的格式规范
• 将 DESIGN.md 与 npm 集成
• 解决 npm 安装错误
• 在 package.json 中使用 designmd
• 使用 designmd 命令
• 集成 DESIGN.md 与其他设计工具

实战：使用 DESIGN.md 定义一个真实的设计系统

我们先创建一个新项目，项目名为 my-design-system。直接运行：

mkdir my-design-system
cd my-design-system

接着，我们需要初始化一个新的 npm 项目，运行：

npm init -y

然后，我们安装 @google/design.md 包：

npm install @google/design.md

如果你遇到 npm error ENOVERSIONS，检查你的 registry 配置：

npm config get registry

应该是 https://registry.npmjs.org/，如果不是，修改配置并重试安装。

现在，我们创建一个 DESIGN.md 文件，添加以下内容：

---
primary: '#3498db'
secondary: '#f1c40f'
---
# 颜色
## 主色
我们的主色是 `primary`，对应的颜色值是 `#3498db`。
## 次色
我们的次色是 `secondary`，对应的颜色值是 `#f1c40f`。

这里，我们定义了两个颜色变量 primary 和 secondary，并在 markdown 体中解释了它们的含义。

接下来，我们使用 designmd 命令来验证我们的 DESIGN.md 文件：

npx designmd validate DESIGN.md

如果没有错误，表明我们的 DESIGN.md 文件是有效的。

集成 DESIGN.md 与其他设计工具

我们可以使用 DESIGN.md 文件来生成设计规范文档，或将其与设计工具如 Sketch 或 Figma 集成。例如，我们可以使用 designmd 命令来生成一个 JSON 文件，包含我们的设计系统信息：

npx designmd json DESIGN.md > design-system.json

然后，我们可以将这个 JSON 文件导入到 Sketch 或 Figma 中，来使用我们的设计系统。

本章小结

• 创建一个新项目并初始化一个新的 npm 项目
• 安装 @google/design.md 包
• 创建一个 DESIGN.md 文件并定义设计系统
• 使用 designmd 命令来验证 DESIGN.md 文件
• 集成 DESIGN.md 与其他设计工具

问题：如何安装design.md？

设计.md的安装可以通过npm进行，命令为npm install @google/design.md，在Windows系统中，需要对包名进行引号括起来，如npm install "@google/design.md"。

问题：design.md文件的结构是什么？

设计.md文件由两部分组成：YAML前置内容和Markdown正文。YAML前置内容用于定义机器可读的设计令牌，Markdown正文则提供了人可读的设计理念和解释。

问题：如何使用design.md命令行工具进行lint和diff操作？

使用npx @google/design.md lint DESIGN.md命令可以对设计文件进行lint检查，使用npx @google/design.md diff DESIGN.md DESIGN-v2.md命令可以对两个设计文件进行比较，检测出令牌级别和正文的变化。

问题：design.md支持哪些令牌类型？

设计.md支持多种令牌类型，包括Color（颜色）、Dimension（尺寸）、Token Reference（令牌引用）、Typography（字体）等。

问题：如何定义组件令牌？

组件令牌可以通过在YAML前置内容中定义components部分来实现，例如：

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

问题：设计.md如何处理未知内容？

设计.md对于未知的内容有特定的处理行为，例如，对于未知的节标题，会保留但不报错；对于未知的颜色令牌名称，如果值是有效的，则会接受；对于未知的字体令牌名称，会接受为有效的字体；对于未知的组件属性，会接受但发出警告。

问题：如何解决Windows/PowerShell下npx命令无输出的问题？

在Windows/PowerShell下，可能会遇到npx命令无输出的问题，这是因为.md后缀与Windows的Markdown文件关联冲突导致的，可以使用npx -p @google/design.md designmd lint DESIGN.md命令来解决。