google-labs-code--design.md/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

DESIGN.md

用于向编码智能体（coding agents）描述视觉识别体系的格式规范。DESIGN.md 让智能体对设计系统形成持久、结构化的理解。

格式（The Format）

DESIGN.md 文件将机器可读的设计令牌（YAML front matter）与人工可读的设计 rationale（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
  label-caps:
    fontFamily: Space Grotesk
    fontSize: 0.75rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

## Overview

Architectural Minimalism meets Journalistic Gravitas. The UI evokes a
premium matte finish — a high-end broadsheet or contemporary gallery.

## Colors

The palette is rooted in high-contrast neutrals and a single accent color.

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
- **Neutral (#F7F5F2):** Warm limestone foundation, softer than pure white.

读取此文件的智能体将生成 UI：Public Sans 字体的深色墨 headlines、温暖的石灰岩（limestone）背景，以及 Boston Clay 风格的 call-to-action 按钮。

快速开始（Getting Started）

根据规范校验 DESIGN.md、捕获损坏的令牌引用、检查 WCAG 对比度，并呈现结构化发现——均以结构化 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 }
}

比较设计系统的两个版本，检测令牌级与正文回归：

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

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

规范（The Specification）

完整的 DESIGN.md 规范见 docs/spec.md。以下为精简参考。

文件结构（File Structure）

DESIGN.md 文件包含两层：

1. YAML front matter — 机器可读的设计令牌，位于文件顶部，由 --- 围栏界定。
2. Markdown body — 人工可读的设计 rationale，按 ## 章节组织。

令牌为规范性数值；正文提供如何应用它们的上下文。

令牌模式（Token Schema）

version: <string>          # optional, current: "alpha"
name: <string>
description: <string>      # optional
colors:
  <token-name>: <Color>
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>

令牌类型（Token Types）

Type	Format	Example
Color	Any CSS color (hex, rgb(), oklch(), named, etc.)	"#1A1C1E", "oklch(62% 0.18 250)"
Dimension	number + unit (px, em, rem)	48px, -0.02em
Token Reference	{path.to.token}	{colors.primary}
Typography	object with fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation	See example above

章节顺序（Section Order）

章节使用 ## 标题。可省略，但已出现的章节须按此顺序排列：

#	Section	Aliases
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

组件令牌（Component Tokens）

组件将名称映射到一组子令牌属性：

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）以独立组件条目表示，并使用相关的键名。

未知内容的消费方行为（Consumer Behavior for Unknown Content）

Scenario	Behavior
Unknown section heading	Preserve; do not error
Unknown color token name	Accept if value is valid
Unknown typography token name	Accept as valid typography
Unknown component property	Accept with warning
Duplicate section heading	Error; reject the file

CLI 参考（CLI Reference）

安装（Installation）

npm install @google/design.md

在 Windows 上，若 shell 对 @ 有特殊处理（PowerShell、部分终端），请为包名加引号：

npm install "@google/design.md"

或直接运行（始终从公共 npm registry 解析）：

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 shim 解析到同一入口点，在所有平台上行为一致。

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

CLI 以 @google/design.md on npm. ENOVERSIONS 几乎总是表示 npm 未查询公共 registry（.npmrc 中的自定义 registry=、尚未同步此包的企业镜像，或 @google 范围的 @google:registry 配置错误）。

检查实际生效的 registry：

npm config get registry

从互联网正常安装时，应为 https://registry.npmjs.org/。修复配置后，若曾缓存过期的 404，请用 npm cache clean --force 重试。

所有命令接受文件路径或 -（stdin）。默认输出为 JSON。

Windows 提示：从 package.json 脚本直接调用 CLI（而非通过 npx）时，请使用 designmd 别名，而非 design.md。原始 bin 名称中的 .md 后缀会使 Windows 命令解析与 Markdown 文件关联混淆。designmd shim 解析到同一入口点，在所有平台上行为一致。

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

lint

校验 DESIGN.md 文件的结构正确性。

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

Option	Type	Default	Description
file	positional	required	Path to DESIGN.md (or - for stdin)
--format	json	json	Output format

若发现错误，退出码为 1；否则为 0。

diff

比较两个 DESIGN.md 文件并报告令牌级变更。

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

Option	Type	Default	Description
before	positional	required	Path to the "before" DESIGN.md
after	positional	required	Path to the "after" DESIGN.md
--format	json	json	Output format

若在 "after" 文件中检测到回归（更多错误或警告），退出码为 1。

export

将 DESIGN.md 中的 token 导出为其他格式。

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

选项	类型	默认值	说明
file	positional	required	DESIGN.md 的路径（或 - 表示从 stdin 读取）
--format	json-tailwind | css-tailwind | tailwind | dtcg	required	输出格式

格式	输出	说明
json-tailwind	JSON	Tailwind v3 的 theme.extend 配置对象
css-tailwind	CSS	带 CSS 自定义属性的 Tailwind v4 @theme { ... } 代码块
tailwind	JSON	json-tailwind 的别名
dtcg	JSON	W3C Design Tokens Format Module

导出成功时退出码为 0（无论源文件中是否存在 lint 发现问题——可运行 lint 以据此进行门禁检查），--format 无效或 emitter 出错时为 1，输入文件无法读取时为 2。

spec

输出 DESIGN.md 格式规范（适用于将规范上下文注入 agent 提示词）。

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

选项	类型	默认值	说明
--rules	boolean	false	追加当前活跃的 lint 规则表
--rules-only	boolean	false	仅输出 lint 规则表
--format	markdown | json	markdown	输出格式

Lint 规则

linter 会对解析后的 DESIGN.md 运行九条规则。每条规则会以固定的严重级别产生发现项（finding）。

规则	严重级别	检查内容
broken-ref	error	无法解析到任何已定义 token 的 token 引用（{colors.primary}）
missing-primary	warning	已定义颜色但未存在 primary 颜色——agent 将自动生成一个
contrast-ratio	warning	组件 backgroundColor/textColor 对比度低于 WCAG AA 最低要求（4.5:1）
orphaned-tokens	warning	已定义颜色 token 但未被任何组件引用
token-summary	info	各节中已定义 token 数量的摘要
missing-sections	info	存在其他 token 时，可选节（spacing、rounded）缺失
missing-typography	warning	已定义颜色但不存在 typography token——agent 将使用默认字体
section-order	warning	各节顺序与规范定义的规范顺序不一致
unknown-key	warning	顶层 YAML 键疑似已知 schema 键的拼写错误（例如 colours: → colors:）；自定义扩展键保持静默

编程式 API

linter 也可作为库使用：

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

const report = lint(markdownString);

console.log(report.findings);       // Finding[]
console.log(report.summary);        // { errors, warnings, info }
console.log(report.designSystem);   // Parsed DesignSystemState

设计令牌互操作性（Design Token Interoperability）

DESIGN.md 中的 token 受 W3C Design Token Format. export 命令可将 token 转换为其他格式：

• Tailwind v3 config (JSON) — npx @google/design.md export --format json-tailwind DESIGN.md — 为 tailwind.config.js 生成 theme.extend JSON 对象。--format tailwind 是向后兼容的别名。
• Tailwind v4 theme (CSS) — npx @google/design.md export --format css-tailwind DESIGN.md — 使用 Tailwind v4 的 CSS 变量 token 命名空间（--color-*、--font-*、--text-*、--leading-*、--tracking-*、--font-weight-*、--radius-*、--spacing-*）生成 CSS @theme { ... } 代码块。
• DTCG tokens.json (W3C Design Tokens Format Module) — npx @google/design.md export --format dtcg DESIGN.md

状态

DESIGN.md 格式当前版本为 alpha。规范、token schema 与 CLI 仍在积极开发中。随着格式逐步成熟，预计会有变更。

免责声明

本项目不符合 Google Open Source Software Vulnerability Rewards Program. 的参与资格