docs: make Chinese README the default

2026-07-13 10:07:22 +00:00
parent ad2a7296b6
commit 196781bcdc
1 changed files with 82 additions and 85 deletions
@@ -1,10 +1,16 @@
+<!-- WEHUB_ZH_README -->
+> [!NOTE]
+> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
+> [English](./README.en.md) · [原始项目](https://github.com/google-labs-code/design.md) · [上游 README](https://github.com/google-labs-code/design.md/blob/HEAD/README.md)  
+> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
+
 # 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.
+用于向编码智能体（coding agents）描述视觉识别体系的格式规范。DESIGN.md 让智能体对设计系统形成持久、结构化的理解。

-## The Format
+## 格式（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 front matter）与人工可读的设计 rationale（Markdown 正文）结合在一起。令牌提供精确数值；正文说明这些数值*为何*存在以及如何应用。

 ```md
 ---
@@ -47,11 +53,11 @@ The palette is rooted in high-contrast neutrals and a single accent color.
 - **Neutral (#F7F5F2):** Warm limestone foundation, softer than pure white.
 ```

-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 字体的深色墨 headlines、温暖的石灰岩（limestone）背景，以及 Boston Clay 风格的 call-to-action 按钮。

-## Getting Started
+## 快速开始（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 输出，供智能体执行。

 ```bash
 npx @google/design.md lint DESIGN.md
@@ -70,7 +76,7 @@ npx @google/design.md lint DESIGN.md
 }
 ```

-Compare two versions of a design system to detect token-level and prose regressions:
+比较设计系统的两个版本，检测令牌级与正文回归：

 ```bash
 npx @google/design.md diff DESIGN.md DESIGN-v2.md
@@ -86,20 +92,20 @@ npx @google/design.md diff DESIGN.md DESIGN-v2.md
 }
 ```

-## The Specification
+## 规范（The Specification）

-The full DESIGN.md spec lives at [`docs/spec.md`](docs/spec.md). What follows is a condensed reference.
+完整的 DESIGN.md 规范见 [`docs/spec.md`](docs/spec.md)。以下为精简参考。

-### File Structure
+### 文件结构（File Structure）

-A DESIGN.md file has two layers:
+DESIGN.md 文件包含两层：

-1. **YAML front matter** — Machine-readable design tokens, delimited by `---` fences at the top of the file.
-2. **Markdown body** — Human-readable design rationale organized into `##` sections.
+1. **YAML front matter** — 机器可读的设计令牌，位于文件顶部，由 `---` 围栏界定。
+2. **Markdown body** — 人工可读的设计 rationale，按 `##` 章节组织。

-The tokens are the normative values. The prose provides context for how to apply them.
+令牌为规范性数值；正文提供如何应用它们的上下文。

-### Token Schema
+### 令牌模式（Token Schema）

 ```yaml
 version: <string>          # optional, current: "alpha"
@@ -118,7 +124,7 @@ components:
    <token-name>: <string | token reference>
 ```

-### Token Types
+### 令牌类型（Token Types）

 | Type | Format | Example |
 |:-----|:-------|:--------|
@@ -127,9 +133,9 @@ components:
 | Token Reference | `{path.to.token}` | `{colors.primary}` |
 | Typography | object with `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation` | See example above |

-### Section Order
+### 章节顺序（Section Order）

-Sections use `##` headings. They can be omitted, but those present must appear in this order:
+章节使用 `##` 标题。可省略，但已出现的章节须按此顺序排列：

 | # | Section | Aliases |
 |:--|:--------|:--------|
@@ -142,9 +148,9 @@ Sections use `##` headings. They can be omitted, but those present must appear i
 | 7 | Components | |
 | 8 | Do's and Don'ts | |

-### Component Tokens
+### 组件令牌（Component Tokens）

-Components map a name to a group of sub-token properties:
+组件将名称映射到一组子令牌属性：

 ```yaml
 components:
@@ -157,11 +163,11 @@ components:
    backgroundColor: "{colors.tertiary-container}"
 ```

-Valid component properties: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`.
+有效的组件属性：`backgroundColor`、`textColor`、`typography`、`rounded`、`padding`、`size`、`height`、`width`。

-Variants (hover, active, pressed) are expressed as separate component entries with a related key name.
+变体（hover、active、pressed）以独立组件条目表示，并使用相关的键名。

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

 | Scenario | Behavior |
 |:---------|:---------|
@@ -171,58 +177,49 @@ Variants (hover, active, pressed) are expressed as separate component entries wi
 | Unknown component property | Accept with warning |
 | Duplicate section heading | Error; reject the file |

-## CLI Reference
+## CLI 参考（CLI Reference）

-### Installation
+### 安装（Installation）

 ```bash
 npm install @google/design.md
 ```

-On **Windows**, quote the package name if your shell treats `@` specially (PowerShell, some terminals):
+在 **Windows** 上，若 shell 对 `@` 有特殊处理（PowerShell、部分终端），请为包名加引号：

 ```bash
 npm install "@google/design.md"
 ```

-Or run directly (always resolves from the public npm registry):
+或直接运行（始终从公共 npm registry 解析）：

 ```bash
 npx @google/design.md lint DESIGN.md
 ```

-On **Windows/PowerShell**, this direct form can produce no output (or open
-`DESIGN.md` in your Markdown editor) because the `.md` suffix in the `design.md`
-bin name collides with the Windows Markdown file association during command
-resolution. Run the dot-free `designmd` alias instead — point `npx` at the
-package with `-p`, then invoke `designmd`:
+在 **Windows/PowerShell** 上，此直接形式可能无输出（或在 Markdown 编辑器中打开 `DESIGN.md`），因为 `design.md` bin 名称中的 `.md` 后缀在命令解析时会与 Windows 的 Markdown 文件关联冲突。请改用不含点号的 `designmd` 别名——用 `-p` 将 `npx` 指向该包，再调用 `designmd`：

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

-The `designmd` shim resolves to the same entrypoint and works identically across
-all platforms.
+`designmd` shim 解析到同一入口点，在所有平台上行为一致。

-#### `npm error ENOVERSIONS` (“No versions available for @google/design.md”)
+#### `npm error ENOVERSIONS`（“No versions available for @google/design.md”）

-The CLI is published as [`@google/design.md` on npm](https://www.npmjs.com/package/@google/design.md). `ENOVERSIONS` almost always means npm is not querying the public registry (custom `registry=` in `.npmrc`, a corporate mirror that has not synced this package, or a misconfigured `@google:registry` for the `@google` scope).
+CLI 以 [`@google/design.md` on npm](https://www.npmjs.com/package/@google/design.md). `ENOVERSIONS` 几乎总是表示 npm 未查询公共 registry（`.npmrc` 中的自定义 `registry=`、尚未同步此包的企业镜像，或 `@google` 范围的 `@google:registry` 配置错误）。

-Check your effective registry:
+检查实际生效的 registry：

 ```bash
 npm config get registry
 ```

-For a normal install from the internet it should be `https://registry.npmjs.org/`. After fixing config, retry with `npm cache clean --force` if a stale 404 was cached.
+从互联网正常安装时，应为 `https://registry.npmjs.org/`。修复配置后，若曾缓存过期的 404，请用 `npm cache clean --force` 重试。

-All commands accept a file path or `-` for stdin. Output defaults to JSON.
+所有命令接受文件路径或 `-`（stdin）。默认输出为 JSON。

-> **Windows tip**: when invoking the CLI directly from a `package.json` script
-> (rather than through `npx`), use the `designmd` alias instead of `design.md`.
-> The `.md` suffix in the original bin name confuses Windows command resolution
-> with the file association for Markdown files. The `designmd` shim resolves to
-> the same entrypoint and works identically across all platforms.
+> **Windows 提示**：从 `package.json` 脚本直接调用 CLI（而非通过 `npx`）时，请使用 `designmd` 别名，而非 `design.md`。原始 bin 名称中的 `.md` 后缀会使 Windows 命令解析与 Markdown 文件关联混淆。`designmd` shim 解析到同一入口点，在所有平台上行为一致。
 >
 > ```jsonc
 > // package.json
@@ -235,7 +232,7 @@ All commands accept a file path or `-` for stdin. Output defaults to JSON.

 ### `lint`

-Validate a DESIGN.md file for structural correctness.
+校验 DESIGN.md 文件的结构正确性。

 ```bash
 npx @google/design.md lint DESIGN.md
@@ -248,11 +245,11 @@ cat DESIGN.md | npx @google/design.md lint -
 | `file` | positional | required | Path to DESIGN.md (or `-` for stdin) |
 | `--format` | `json` | `json` | Output format |

-Exit code `1` if errors are found, `0` otherwise.
+若发现错误，退出码为 `1`；否则为 `0`。

 ### `diff`

-Compare two DESIGN.md files and report token-level changes.
+比较两个 DESIGN.md 文件并报告令牌级变更。

 ```bash
 npx @google/design.md diff DESIGN.md DESIGN-v2.md
@@ -264,11 +261,11 @@ npx @google/design.md diff DESIGN.md DESIGN-v2.md
 | `after` | positional | required | Path to the "after" DESIGN.md |
 | `--format` | `json` | `json` | Output format |

-Exit code `1` if regressions are detected (more errors or warnings in the "after" file).
+若在 "after" 文件中检测到回归（更多错误或警告），退出码为 `1`。

 ### `export`

-Export DESIGN.md tokens to other formats.
+将 DESIGN.md 中的 token 导出为其他格式。

 ```bash
 npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
@@ -276,23 +273,23 @@ npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
 npx @google/design.md export --format dtcg DESIGN.md > tokens.json
 ```

-| Option | Type | Default | Description |
+| 选项 | 类型 | 默认值 | 说明 |
 |:-------|:-----|:--------|:------------|
-| `file` | positional | required | Path to DESIGN.md (or `-` for stdin) |
-| `--format` | `json-tailwind` \| `css-tailwind` \| `tailwind` \| `dtcg` | required | Output format |
+| `file` | positional | required | DESIGN.md 的路径（或 `-` 表示从 stdin 读取） |
+| `--format` | `json-tailwind` \| `css-tailwind` \| `tailwind` \| `dtcg` | required | 输出格式 |

-| Format | Output | Description |
+| 格式 | 输出 | 说明 |
 |:-------|:-------|:------------|
-| `json-tailwind` | JSON | Tailwind v3 `theme.extend` config object |
-| `css-tailwind` | CSS | Tailwind v4 `@theme { ... }` block with CSS custom properties |
-| `tailwind` | JSON | Alias for `json-tailwind` |
+| `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 |

-Exit code `0` on a successful export (regardless of any lint findings in the source — run `lint` to gate on those), `1` on an invalid `--format` or an emitter error, and `2` if the input file cannot be read.
+导出成功时退出码为 `0`（无论源文件中是否存在 lint 发现问题——可运行 `lint` 以据此进行门禁检查），`--format` 无效或 emitter 出错时为 `1`，输入文件无法读取时为 `2`。

 ### `spec`

-Output the DESIGN.md format specification (useful for injecting spec context into agent prompts).
+输出 DESIGN.md 格式规范（适用于将规范上下文注入 agent 提示词）。

 ```bash
 npx @google/design.md spec
@@ -300,31 +297,31 @@ npx @google/design.md spec --rules
 npx @google/design.md spec --rules-only --format json
 ```

-| Option | Type | Default | Description |
+| 选项 | 类型 | 默认值 | 说明 |
 |:-------|:-----|:--------|:------------|
-| `--rules` | boolean | `false` | Append the active linting rules table |
-| `--rules-only` | boolean | `false` | Output only the linting rules table |
-| `--format` | `markdown` \| `json` | `markdown` | Output format |
+| `--rules` | boolean | `false` | 追加当前活跃的 lint 规则表 |
+| `--rules-only` | boolean | `false` | 仅输出 lint 规则表 |
+| `--format` | `markdown` \| `json` | `markdown` | 输出格式 |

-## Linting Rules
+## Lint 规则

-The linter runs nine rules against a parsed DESIGN.md. Each rule produces findings at a fixed severity level.
+linter 会对解析后的 DESIGN.md 运行九条规则。每条规则会以固定的严重级别产生发现项（finding）。

-| Rule | Severity | What it checks |
+| 规则 | 严重级别 | 检查内容 |
 |:-----|:---------|:---------------|
-| `broken-ref` | error | Token references (`{colors.primary}`) that don't resolve to any defined token |
-| `missing-primary` | warning | Colors are defined but no `primary` color exists — agents will auto-generate one |
-| `contrast-ratio` | warning | Component `backgroundColor`/`textColor` pairs below WCAG AA minimum (4.5:1) |
-| `orphaned-tokens` | warning | Color tokens defined but never referenced by any component |
-| `token-summary` | info | Summary of how many tokens are defined in each section |
-| `missing-sections` | info | Optional sections (spacing, rounded) absent when other tokens exist |
-| `missing-typography` | warning | Colors are defined but no typography tokens exist — agents will use default fonts |
-| `section-order` | warning | Sections appear out of the canonical order defined by the spec |
-| `unknown-key` | warning | A top-level YAML key looks like a typo of a known schema key (e.g. `colours:` → `colors:`); custom extension keys stay silent |
+| `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:`）；自定义扩展键保持静默 |

-### Programmatic API
+### 编程式 API

-The linter is also available as a library:
+linter 也可作为库使用：

 ```typescript
 import { lint } from '@google/design.md/linter';
@@ -336,19 +333,19 @@ console.log(report.summary);        // { errors, warnings, info }
 console.log(report.designSystem);   // Parsed DesignSystemState
 ```

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

-DESIGN.md tokens are inspired by the [W3C Design Token Format](https://www.designtokens.org/). The `export` command converts tokens to other formats:
+DESIGN.md 中的 token 受 [W3C Design Token Format](https://www.designtokens.org/). `export` 命令可将 token 转换为其他格式：

- **Tailwind v3 config (JSON)** — `npx @google/design.md export --format json-tailwind DESIGN.md` — emits a `theme.extend` JSON object for `tailwind.config.js`. `--format tailwind` is a backwards-compatible alias.
- **Tailwind v4 theme (CSS)** — `npx @google/design.md export --format css-tailwind DESIGN.md` — emits a CSS `@theme { ... }` block using Tailwind v4's CSS-variable token namespaces (`--color-*`, `--font-*`, `--text-*`, `--leading-*`, `--tracking-*`, `--font-weight-*`, `--radius-*`, `--spacing-*`).
+- **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](https://tr.designtokens.org/format/)) — `npx @google/design.md export --format dtcg DESIGN.md`

-## Status
+## 状态

-The DESIGN.md format is at version `alpha`. The spec, token schema, and CLI are under active development. Expect changes to the format as it matures.
+DESIGN.md 格式当前版本为 `alpha`。规范、token schema 与 CLI 仍在积极开发中。随着格式逐步成熟，预计会有变更。

-## Disclaimer
+## 免责声明

-This project is not eligible for the [Google Open Source Software Vulnerability
-Rewards Program](https://bughunters.google.com/open-source-security).
+本项目不符合 [Google Open Source Software Vulnerability
+Rewards Program](https://bughunters.google.com/open-source-security). 的参与资格