google-labs-code design.md

好的，这是您要求的英文文章的中文翻译，已按照规范处理。

概述

建筑极简主义与新闻庄重感相遇。用户界面呈现出一种高级哑光质感——如同高端对开报纸或当代画廊。

色彩

调色板植根于高对比度的中性色和单一强调色。

主色 (#1A1C1E)： 用于标题和核心文字的深墨色。
辅色 (#6C7278)： 用于边框、说明文字、元数据的精致石板灰。
强调色 (#B8422E)： “波士顿陶土”——交互的唯一驱动力。
中性色 (#F7F5F2)： 温暖的石灰岩底色，比纯白色更柔和。

读取此文件的 agent 将生成一个用户界面，其中包含使用 Public Sans 字体的深墨色标题、温暖的石灰岩背景以及波士顿陶土色的行动号召按钮。

快速开始

根据规范验证 DESIGN.md 文件，捕获损坏的 token 引用，检查 WCAG 对比度比率，并呈现结构性发现——全部以 agent 可操作的、结构化的 JSON 格式输出。

npx @google/design.md lint DESIGN.md

{
  "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
  }
}

比较两个版本的设计系统，以检测 token 级别和散文级别的回归：

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

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

规范

完整的 DESIGN.md 规范位于 docs/spec.md。以下是精简参考。

文件结构

一个 DESIGN.md 文件包含两层：

YAML 前置元数据 — 机器可读的设计 token，由文件顶部的 --- 分隔符界定。
Markdown 正文 — 按 ## 章节组织的人类可读设计原理。

Token 是规范性值。散文提供了如何应用它们的上下文。

Token 模式

version:         # 可选，当前版本: "alpha"
name: 
description:     # 可选
colors:
  : 
typography:
  : 
rounded:
  : 
spacing:
  : 
components:
  :
    :

Token 类型

| 类型 | 格式 | 示例 | | :--- | :--- | :--- | | Color | 任何 CSS 颜色（hex, rgb(), oklch(), 命名颜色等） | "#1A1C1E", "oklch(62% 0.18 250)" | | Dimension | 数字 + 单位（px, em, rem） | 48px, -0.02em | | Token Reference | {path.to.token} | {colors.primary} | | Typography | 包含 fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation 的对象 | 见上方示例 |

章节顺序

章节使用 ## 标题。它们可以被省略，但如果存在，必须按此顺序出现：

| # | 章节 | 别名 | | :--- | :--- | :--- | | 1 | Overview | Brand & Style | | 2 | Colors | | | 3 | Typography | | | 4 | Layout | Layout & Spacing | | 5 | Elevation & Depth | Elevation | | 6 | Shapes | | | 7 | Components | | | 8 | Do's and Don'ts | |

组件 Token

组件将一个名称映射到一组子 token 属性：

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

有效的组件属性：backgroundColor, textColor, typography, rounded, padding, size, height, width。

变体（hover, active, pressed）通过具有相关键名的独立组件条目来表达。

对未知内容的消费者行为

CLI 参考

安装

npm install @google/design.md

在 Windows 上，如果您的 shell（PowerShell，某些终端）特殊对待 @ 符号，请将包名用引号括起来：

npm install "@google/design.md"

或者直接运行（始终从公共 npm 注册表解析）：

npx @google/design.md lint DESIGN.md

在 Windows/PowerShell 上，这种直接形式可能不产生输出（或在您的 Markdown 编辑器中打开 DESIGN.md），因为 design.md bin 名称中的 .md 后缀在命令解析期间与 Windows Markdown 文件关联冲突。请改用无点的 designmd 别名——使用 -p 将 npx 指向该包，然后调用 designmd：

npx -p @google/design.md designmd lint DESIGN.md

designmd 垫片解析到相同的入口点，并在所有平台上工作相同。

npm error ENOVERSIONS（“No versions available for @google/design.md”）

CLI 在 npm 上以 @google/design.md 发布。ENOVERSIONS 几乎总是意味着 npm 没有查询公共注册表（.npmrc 中的自定义 registry=，未同步此包的公司镜像，或 @google 作用域的错误配置的 @google:registry）。检查您的有效注册表：

npm config get registry

对于从互联网正常安装，它应该是 https://registry.npmjs.org/。修复配置后，如果缓存了过时的 404，请使用 npm cache clean --force 重试。

所有命令都接受文件路径或 - 以从标准输入读取。输出默认为 JSON。

Windows 提示：当从 package.json 脚本（而非通过 npx）直接调用 CLI 时，请使用 designmd。