wehub-resource-sync
352 lines
12 KiB
Markdown
352 lines
12 KiB
Markdown
<!-- 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
|
||
|
||
用于向编码智能体（coding agents）描述视觉识别体系的格式规范。DESIGN.md 让智能体对设计系统形成持久、结构化的理解。
|
||
|
||
## 格式（The Format）
|
||
|
||
DESIGN.md 文件将机器可读的设计令牌（YAML front matter）与人工可读的设计 rationale（Markdown 正文）结合在一起。令牌提供精确数值；正文说明这些数值*为何*存在以及如何应用。
|
||
|
||
```md
|
||
---
|
||
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 输出，供智能体执行。
|
||
|
||
```bash
|
||
npx @google/design.md lint DESIGN.md
|
||
```
|
||
|
||
```json
|
||
{
|
||
"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 }
|
||
}
|
||
```
|
||
|
||
比较设计系统的两个版本，检测令牌级与正文回归：
|
||
|
||
```bash
|
||
npx @google/design.md diff DESIGN.md DESIGN-v2.md
|
||
```
|
||
|
||
```json
|
||
{
|
||
"tokens": {
|
||
"colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
|
||
"typography": { "added": [], "removed": [], "modified": [] }
|
||
},
|
||
"regression": false
|
||
}
|
||
```
|
||
|
||
## 规范（The Specification）
|
||
|
||
完整的 DESIGN.md 规范见 [`docs/spec.md`](docs/spec.md)。以下为精简参考。
|
||
|
||
### 文件结构（File Structure）
|
||
|
||
DESIGN.md 文件包含两层：
|
||
|
||
1. **YAML front matter** — 机器可读的设计令牌，位于文件顶部，由 `---` 围栏界定。
|
||
2. **Markdown body** — 人工可读的设计 rationale，按 `##` 章节组织。
|
||
|
||
令牌为规范性数值；正文提供如何应用它们的上下文。
|
||
|
||
### 令牌模式（Token Schema）
|
||
|
||
```yaml
|
||
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）
|
||
|
||
组件将名称映射到一组子令牌属性：
|
||
|
||
```yaml
|
||
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）
|
||
|
||
```bash
|
||
npm install @google/design.md
|
||
```
|
||
|
||
在 **Windows** 上，若 shell 对 `@` 有特殊处理（PowerShell、部分终端），请为包名加引号：
|
||
|
||
```bash
|
||
npm install "@google/design.md"
|
||
```
|
||
|
||
或直接运行（始终从公共 npm registry 解析）：
|
||
|
||
```bash
|
||
npx @google/design.md lint DESIGN.md
|
||
```
|
||
|
||
在 **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
|
||
```
|
||
|
||
`designmd` shim 解析到同一入口点，在所有平台上行为一致。
|
||
|
||
#### `npm error ENOVERSIONS`（“No versions available for @google/design.md”）
|
||
|
||
CLI 以 [`@google/design.md` on npm](https://www.npmjs.com/package/@google/design.md). `ENOVERSIONS` 几乎总是表示 npm 未查询公共 registry（`.npmrc` 中的自定义 `registry=`、尚未同步此包的企业镜像，或 `@google` 范围的 `@google:registry` 配置错误）。
|
||
|
||
检查实际生效的 registry：
|
||
|
||
```bash
|
||
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 解析到同一入口点，在所有平台上行为一致。
|
||
>
|
||
> ```jsonc
|
||
> // package.json
|
||
> {
|
||
> "scripts": {
|
||
> "design:lint": "designmd lint DESIGN.md"
|
||
> }
|
||
> }
|
||
> ```
|
||
|
||
### `lint`
|
||
|
||
校验 DESIGN.md 文件的结构正确性。
|
||
|
||
```bash
|
||
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 文件并报告令牌级变更。
|
||
|
||
```bash
|
||
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 导出为其他格式。
|
||
|
||
```bash
|
||
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 提示词）。
|
||
|
||
```bash
|
||
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 也可作为库使用：
|
||
|
||
```typescript
|
||
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](https://www.designtokens.org/). `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](https://tr.designtokens.org/format/)) — `npx @google/design.md export --format dtcg DESIGN.md`
|
||
|
||
## 状态
|
||
|
||
DESIGN.md 格式当前版本为 `alpha`。规范、token schema 与 CLI 仍在积极开发中。随着格式逐步成熟，预计会有变更。
|
||
|
||
## 免责声明
|
||
|
||
本项目不符合 [Google Open Source Software Vulnerability
|
||
Rewards Program](https://bughunters.google.com/open-source-security). 的参与资格
|