google-labs-code / design.md

查看原文 / View Original 编辑 / Edit

google-labs-code / DESIGN.md

DESIGN.md A format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.

DESIGN.md 一种用于向编码智能体（coding agents）描述视觉识别系统的格式规范。DESIGN.md 为智能体提供了一种持久且结构化的设计系统理解方式。

The Format

A DESIGN.md file combines machine-readable design tokens (YAML front matter) with human-readable design rationale (markdown prose). Tokens give agents exact values. Prose tells them why those values exist and how to apply them.

格式

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} 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.

概述

建筑极简主义与新闻庄重感的结合。UI 呈现出一种高级哑光质感——如同高端大报或当代艺术画廊。

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.

颜色

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

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

An agent that reads this file will produce a UI with deep ink headlines in Public Sans, a warm limestone background, and Boston Clay call-to-action buttons.

读取此文件的智能体将生成一个 UI：标题采用 Public Sans 字体的深墨色，背景为温暖的石灰岩色，并配有波士顿陶土色的行动号召（CTA）按钮。

Getting Started

Validate a DESIGN.md against the spec, catch broken token references, check WCAG contrast ratios, and surface structural findings — all as structured JSON that agents can act on.

入门指南

根据规范验证 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 }
}

Compare two versions of a design system to detect token-level and prose regressions:

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

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

The full DESIGN.md spec lives at docs/spec.md. What follows is a condensed reference.

规范

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

File Structure

A DESIGN.md file has two layers:

  • YAML front matter — Machine-readable design tokens, delimited by --- fences at the top of the file.
  • Markdown body — Human-readable design rationale organized into ## sections.

文件结构

DESIGN.md 文件包含两层：

  • YAML 前置元数据 — 机器可读的设计令牌，位于文件顶部，由 --- 分隔。
  • Markdown 正文 — 人类可读的设计原理，组织在 ## 标题下。

The tokens are the normative values. The prose provides context for how to apply them.

令牌是规范值，正文则提供了如何应用这些值的上下文。

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

TypeFormatExample
ColorAny CSS color”#1A1C1E”, “oklch(62% 0.18 250)“
Dimensionnumber + unit48px, -0.02em
Token Reference{path.to.token}{colors.primary}
Typographyobject with fontFamily, fontSize, etc.See example above

令牌类型

类型格式示例
颜色任何 CSS 颜色”#1A1C1E”, “oklch(62% 0.18 250)“
尺寸数字 + 单位48px, -0.02em
令牌引用{path.to.token}{colors.primary}
排版包含 fontFamily, fontSize 等的对象见上文示例

Section Order

Sections use ## headings. They can be omitted, but those present must appear in this order:

章节顺序

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

  1. Overview (Brand & Style)

  2. Colors

  3. Typography

  4. Layout (Layout & Spacing)

  5. Elevation (Elevation & Depth)

  6. Shapes

  7. Components

  8. Do’s and Don’ts

  9. 概述 (品牌与风格)

  10. 颜色

  11. 排版

  12. 布局 (布局与间距)

  13. 高度 (高度与深度)

  14. 形状

  15. 组件

  16. 准则与禁忌

Component Tokens

Components map a name to a group of sub-token properties:

组件令牌

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

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

Valid component properties: backgroundColor, textColor, typography, rounded, padding, size, height, width. Variants (hover, active, pressed) are expressed as separate component entries with a related key name.

有效的组件属性包括：backgroundColor, textColor, typography, rounded, padding, size, height, width。变体（hover, active, pressed）表现为带有相关键名的独立组件条目。

Consumer Behavior for Unknown Content

ScenarioBehavior
Unknown section headingPreserve; do not error
Unknown color token nameAccept if value is valid
Unknown typography token nameAccept as valid typography
Unknown component propertyAccept with warning
Duplicate section headingError; reject the file

对未知内容的消费行为

场景行为
未知章节标题保留；不报错
未知颜色令牌名称若值有效则接受
未知排版令牌名称作为有效排版接受
未知组件属性接受并发出警告
重复章节标题报错；拒绝文件

CLI Reference

Installation

npm install @google/design.md

On Windows, quote the package name if your shell treats @ specially:

npm install "@google/design.md"

CLI 参考

安装

npm install @google/design.md

在 Windows 上，如果你的 Shell 对 @ 有特殊处理，请给包名加上引号：

npm install "@google/design.md"

Or run directly:

npx @google/design.md lint DESIGN.md

或者直接运行：

npx @google/design.md lint DESIGN.md

On Windows/PowerShell, run the dot-free designmd alias instead:

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

在 Windows/PowerShell 上，请改用不带点的 designmd 别名：

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

npm error ENOVERSIONS The CLI is published as @google/design.md on npm. ENOVERSIONS almost always means npm is not querying the public registry. Check your effective registry:

npm config get registry

npm error ENOVERSIONS 该 CLI 在 npm 上发布为 @google/design.md。出现 ENOVERSIONS 通常意味着 npm 没有查询公共注册表。检查你的有效注册表：

npm config get registry

All commands accept a file path or - for stdin. Output defaults to JSON.

所有命令都接受文件路径或 -（用于标准输入）。输出默认为 JSON。

← 返回新闻列表 / Back to news list