design-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Design Language Doc (DESIGN.md)

设计语言文档（DESIGN.md）

You are creating this repository's design-language contract: a root

DESIGN.md

that tells agents and humans exactly how UI is built here, plus a portable

frontend-design

craft skill. The doc is downstream of the code — you describe the design language that exists, or propose one with user approval. You never invent a design language and present it as fact, and you never restyle existing UI to match a doc.

你正在为这个仓库创建设计语言契约：一份根目录下的

DESIGN.md

，用于明确告知Agent与人类该仓库的UI构建方式，同时还要创建一个可移植的

frontend-design

工艺技能。这份文档是代码的下游产物——你需要描述已存在的设计语言，或在获得用户批准后提出设计方案。绝不能凭空编造设计语言并将其当作既定事实，也绝不能为了匹配文档而重新设置现有UI的样式。

Goal

目标

Root
```
DESIGN.md
```
— the repo's design language, written from evidence, citing real files and tokens
```
.agents/skills/frontend-design/SKILL.md
```
— portable craft doctrine (typography, surfaces, motion) that applies to any repo
A link from
```
AGENTS.md
```
so agents find the design language within one hop

根目录
```
DESIGN.md
```
——基于实证编写的仓库设计语言，需引用真实文件与设计令牌
```
.agents/skills/frontend-design/SKILL.md
```
——可移植的工艺准则（排版、界面表层、动效），适用于任何仓库
在
```
AGENTS.md
```
中添加链接，让Agent只需一次跳转即可找到设计语言规范

Reference templates

参考模板

File	Used for
`references/design-md-template.md`	`DESIGN.md` skeleton, filled from evidence
`references/skill-frontend-design.md`	`.agents/skills/frontend-design/SKILL.md` (create verbatim)

文件	用途
`references/design-md-template.md`	`DESIGN.md` 骨架，基于实证填充
`references/skill-frontend-design.md`	`.agents/skills/frontend-design/SKILL.md` （原样创建）

Phase 0: Audit, then classify (before writing anything)

阶段0：先审计，再分类（编写任何内容之前）

Gather evidence. Every claim in

DESIGN.md

must trace back to something you saw here:

```
package.json
```
: framework, UI libraries (react/vue/svelte, tailwind, shadcn, radix/base-ui, motion/framer-motion, lucide, fonts packages)
Token layer:
```
globals.css
```
/
```
tailwind.config.*
```
/ theme files — CSS variables,
```
@theme
```
blocks, custom utilities (shadows, radii, animations)
Fonts: how they're loaded (
```
next/font
```
,
```
@font-face
```
, link tags), which families, which roles
Component system:
```
components/ui/
```
, shared primitives, variant patterns (cva, variants props)
Motion: keyframes, transition utilities, motion-library usage,
```
prefers-reduced-motion
```
handling
The 3–5 most polished surfaces in the app — these define the actual design language, whatever the tokens claim
Existing design docs:
```
DESIGN.md
```
,
```
docs/design*
```
, brand guidelines, Figma links in READMEs, design-related Cursor rules or agent docs

Then classify the repo into exactly one mode:

收集实证。

DESIGN.md

中的每一项声明都必须能追溯到你在仓库中找到的依据：

```
package.json
```
：框架、UI库（react/vue/svelte、tailwind、shadcn、radix/base-ui、motion/framer-motion、lucide、字体包）
令牌层：
```
globals.css
```
/
```
tailwind.config.*
```
/ 主题文件——CSS变量、
```
@theme
```
块、自定义工具类（阴影、圆角、动画）
字体：加载方式（
```
next/font
```
、
```
@font-face
```
、link标签）、字体族、用途
组件系统：
```
components/ui/
```
、共享基础组件、变体模式（cva、variants属性）
动效：关键帧、过渡工具类、动效库使用情况、
```
prefers-reduced-motion
```
适配处理
应用中3-5个最完善的界面——这些定义了实际的设计语言，无论设计令牌如何声明
现有设计文档：
```
DESIGN.md
```
、
```
docs/design*
```
、品牌指南、README中的Figma链接、与设计相关的Cursor规则或Agent文档

然后将仓库精确归类为以下一种模式：

Mode A — Document (established design language, no design doc)

模式A — 记录（已有成熟设计语言，但无设计文档）

The repo has consistent tokens, deliberate font choices, a component system, recurring motifs. Your job is extraction: write

DESIGN.md

describing what exists, citing the files that prove it. Nothing about the actual design changes. Where the codebase is internally inconsistent, document the dominant/most-recent pattern and note the deviation — do not resolve it by fiat.

仓库拥有一致的设计令牌、经过深思熟虑的字体选择、组件系统、反复出现的设计元素。你的任务是提取：编写

DESIGN.md

描述现有设计，并引用可佐证的文件。实际设计不会有任何改动。如果代码库内部存在不一致，记录主流/最新的模式并标注差异——不要擅自统一。

Mode B — Merge (design docs already exist)

模式B — 合并（已有设计文档）

DESIGN.md

, brand guide, or design-related rules already exist. Merge, never regenerate: preserve every unique local rule, deduplicate against the template structure, keep one source of truth, and leave pointers behind if you consolidate scattered docs. If existing docs contradict the code, flag the contradiction to the user instead of silently picking a side.

已经存在

DESIGN.md

、品牌指南或设计相关规则。合并，绝不重新生成：保留每一条独特的本地规则，按照模板结构去重，维护唯一事实来源，如果整合了分散的文档，要留下指向原文档的指针。如果现有文档与代码矛盾，向用户标记矛盾之处，而不是默默选择某一方。

Mode C — Propose (greenfield, no coherent design language)

模式C — 提案（全新项目，无统一设计语言）

No established language exists. Choosing an aesthetic direction is a user-owned decision, not an evidence question. Write a one-page proposal to

docs/plans/design-language.md

(or

PLAN.md

if the repo has no

docs/plans/

) covering: aesthetic direction and tone, font pairing (display + body), color approach and the accent budget, elevation strategy, motion approach. Offer 2–3 distinct directions if the product context supports them. Stop and get user approval before writing
DESIGN.md
. After approval, write the full doc from the approved proposal.

没有成熟的设计语言。选择美学方向是用户的决策，不是实证问题。在

docs/plans/design-language.md

编写一份单页提案（如果仓库没有

docs/plans/

目录则写在

PLAN.md

），内容包括：美学方向与基调、字体搭配（标题+正文）、配色方案与强调色预算、层级策略、动效方案。如果产品场景支持，提供2-3个不同的方向。在编写
DESIGN.md
之前必须暂停并获得用户批准。批准后，根据通过的提案编写完整文档。

Deliverables

交付物

DESIGN.md                              # root design-language contract (living document)
.agents/
  skills/
    frontend-design/SKILL.md           # portable craft doctrine (references/skill-frontend-design.md)
docs/
  plans/
    design-language.md                 # Mode C only: the approved proposal

Plus one edit: add

- [Design Language](DESIGN.md)

to the Quick Links in

AGENTS.md

(create the section if the repo has an

AGENTS.md

without it; skip if there is no

AGENTS.md

DESIGN.md                              # root design-language contract (living document)
.agents/
  skills/
    frontend-design/SKILL.md           # portable craft doctrine (references/skill-frontend-design.md)
docs/
  plans/
    design-language.md                 # Mode C only: the approved proposal

此外还有一项编辑操作：在

AGENTS.md

的快速链接中添加

- [Design Language](DESIGN.md)

（如果仓库有

AGENTS.md

但没有快速链接部分，则创建该部分；如果没有

AGENTS.md

则跳过）。

Process (in order)

流程（按顺序执行）

Phase 0 audit and classification (checklist above)
Mode C only: write the proposal, present it, and wait for approval
Write
```
DESIGN.md
```
using
```
references/design-md-template.md
```
as structure — filled from evidence (Modes A/B) or the approved proposal (Mode C)
Create
```
.agents/skills/frontend-design/SKILL.md
```
verbatim from
```
references/skill-frontend-design.md
```
(stripping the template preamble), unless the repo already has an equivalent craft skill — then skip it
Link
```
DESIGN.md
```
from
```
AGENTS.md
```
Quick Links
Run the verification pass below
Report: mode chosen and why, files created, contradictions found between docs and code, rules preserved from pre-existing docs

阶段0 审计与分类（见上方检查清单）
仅模式C：编写提案，提交给用户，等待批准
以
```
references/design-md-template.md
```
为结构编写
```
DESIGN.md
```
——基于实证填充（模式A/B）或基于已批准的提案填充（模式C）
按照
```
references/skill-frontend-design.md
```
的内容原样创建
```
.agents/skills/frontend-design/SKILL.md
```
（移除模板前言），如果仓库已有等效的工艺技能，则跳过此步
在
```
AGENTS.md
```
的快速链接中添加
```
DESIGN.md
```
的链接
执行下方的验证检查
报告：选择的模式及原因、创建的文件、文档与代码之间的矛盾、从原有文档中保留的规则

Writing rules for DESIGN.md

DESIGN.md编写规则

Cite real files. Every token, utility, font, and component pattern named in the doc must link to the file that defines it
Name the budgets. Great design languages are mostly restraint — make limits explicit ("one accent pairing per view", "at most one display-font moment per page"), because agents follow budgets better than vibes
Include the one-liner. A blockquote near the top that compresses the whole language into one paragraph an agent can carry to another surface
End with a per-page checklist of verifiable items, phrased so an agent can self-review against them
Sizes over adjectives. "
```
rounded-3xl
```
cards,
```
rounded-full
```
CTAs" beats "generously rounded"
Semantic tokens over hardcoded values everywhere the repo's token system reaches; name the sanctioned exceptions explicitly

引用真实文件。 文档中提到的每一个设计令牌、工具类、字体和组件模式都必须链接到定义它的文件
明确预算。 优秀的设计语言很大程度上在于克制——要明确限制（「每个视图最多一对强调色」、「每页最多一处展示字体使用场景」），因为Agent比起来感觉，更擅长遵循明确的预算限制
包含一句话总结。 在文档顶部附近用块引用将整个设计语言浓缩为一段，方便Agent带到其他场景使用
末尾附上每页检查清单，列出可验证的项，表述方式要让Agent能够据此进行自我审查
用具体尺寸代替形容词。 「
```
rounded-3xl
```
卡片、
```
rounded-full
```
CTA」比「大圆角」更好
只要仓库的令牌系统覆盖到的地方，都使用语义化令牌而非硬编码值；明确列出允许的例外情况

Constraints

约束

Never restyle existing components to match
DESIGN.md
. The doc describes or proposes; it does not authorize a refactor. If the user wants the UI brought in line with the doc, that is a separate, explicit task
In Modes A and B, do not "improve" the design language while documenting it — record improvement ideas at the end under a clearly-marked "Open questions" section instead
Do not copy another product's design language (fonts, palettes, motifs) into
```
DESIGN.md
```
unless verified in THIS repo or approved in the Mode C proposal
Prefer an accurate short doc over an impressive long one — an agent that trusts a wrong design doc produces confidently wrong UI
Match the repo's markdown tone and formatting

绝不能为了匹配
DESIGN.md
而重新设置现有组件的样式。文档只做描述或提案，不授权重构。如果用户希望UI与文档保持一致，那是一个单独的、需要明确提出的任务
在模式A和B中，不要在记录设计语言时「改进」它——将改进想法记录在末尾标记清晰的「待讨论问题」部分 instead
不要将其他产品的设计语言（字体、调色板、设计元素）复制到
```
DESIGN.md
```
中，除非在本仓库中得到验证，或在模式C的提案中获得批准
宁可文档简短准确，也不要冗长但看似专业——信任错误设计文档的Agent会产出自信但错误的UI
匹配仓库的markdown语气与格式

Verification pass (required before finishing)

验证检查（完成前必须执行）

Every file path referenced in
```
DESIGN.md
```
resolves to an existing file
Every token, utility class, and font named in the doc exists in the codebase (grep for it)
Modes A/B: no rule in the doc contradicts what the most polished surfaces actually do
Mode B: every unique rule from the pre-existing docs survived the merge (diff them)
Mode C: the doc matches the approved proposal; the proposal file exists in
```
docs/plans/
```
The
```
AGENTS.md
```
link resolves
The checklist at the end of
```
DESIGN.md
```
contains only items an agent can verify from code

```
DESIGN.md
```
中引用的每个文件路径都对应真实存在的文件
文档中提到的每个设计令牌、工具类和字体都存在于代码库中（可通过grep验证）
模式A/B：文档中的规则与最完善的界面实际表现没有矛盾
模式B：原有文档中的每一条独特规则都在合并后保留了下来（可通过diff验证）
模式C：文档与已批准的提案一致；提案文件存在于
```
docs/plans/
```
目录下
```
AGENTS.md
```
中的链接可正常跳转
```
DESIGN.md
```
末尾的检查清单只包含Agent能从代码中验证的项

Done when

完成标准

An agent building UI in this repo can answer "what fonts, what tokens, what radii, what shadows, what motion?" from
```
DESIGN.md
```
alone, one hop from
```
AGENTS.md
```
The user's existing design decisions are intact — nothing was overwritten, and any new direction was explicitly approved
The portable
```
frontend-design
```
craft skill is installed
Every doc statement is evidence-backed (or approval-backed) and the verification pass is clean

在本仓库中构建UI的Agent仅通过
```
DESIGN.md
```
（从
```
AGENTS.md
```
一次跳转即可到达）就能回答「用什么字体、什么令牌、什么圆角、什么阴影、什么动效」的问题
用户现有的设计决策完好无损——没有任何内容被覆盖，任何新方向都得到了明确批准
可移植的
```
frontend-design
```
工艺技能已安装
文档中的每一项陈述都有实证支持（或有批准支持），且验证检查全部通过