design-md

设计语言文档（DESIGN.md）

你正在为此代码库制定设计语言规范：在根目录创建 DESIGN.md，明确告诉 Agent 和人类这里的 UI 是如何构建的，并提供一份可移植的 frontend-design 工艺指南。该文档应以代码为依据——描述已经存在的设计语言，或者在获得用户批准后提出一种设计语言。绝不能凭空创造设计语言并将其说成既成事实，也绝不能为了符合文档而重新设计现有 UI。

目标

1. 根目录的 DESIGN.md——基于证据撰写代码库的设计语言，并引用实际文件和设计令牌
2. .agents/skills/frontend-design/SKILL.md——可移植的工艺准则（排版、表面、动效），适用于任何代码库
3. 在 AGENTS.md 中添加链接，让 Agent 一步即可找到设计语言

参考模板

文件	用途
references/design-md-template.md	DESIGN.md 骨架，根据证据填写
references/skill-frontend-design.md	.agents/skills/frontend-design/SKILL.md（照原文创建）

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

收集证据。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、链接标签）、字体系列及其用途
• 组件系统：components/ui/、共享基础组件、变体模式（cva、variants 属性）
• 动效：关键帧、过渡工具类、动效库的使用、对 prefers-reduced-motion 的处理
• 应用中打磨最完善的 3–5 个界面——无论设计令牌声称什么，它们定义的都是实际设计语言
• 现有设计文档：DESIGN.md、docs/design*、品牌指南、README 中的 Figma 链接、与设计相关的 Cursor 规则或 Agent 文档

然后将代码库准确归入以下一种模式：

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

代码库具有一致的设计令牌、经过审慎选择的字体、组件系统和反复出现的设计元素。你的工作是提取：撰写 DESIGN.md，描述现有内容，并引用能证明这一点的文件。实际设计一律不得更改。如果代码库内部存在不一致，应记录占主导地位或最新的模式，并注明偏差——不得擅自解决。

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

已经存在 DESIGN.md、品牌指南或与设计相关的规则。应合并，绝不重新生成：保留所有独有的本地规则，按照模板结构去重，确保只有一个事实来源；如果合并了分散的文档，应留下指引链接。如果现有文档与代码矛盾，应向用户指出矛盾，而不是擅自选择一方。

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

目前尚无成熟的设计语言。选择美学方向是由用户决定，而非通过证据得出的结论。请在 docs/plans/design-language.md（如果代码库没有 docs/plans/，则使用 PLAN.md）中撰写一页提案，涵盖：美学方向与基调、字体搭配（展示字体 + 正文字体）、配色方案与强调色预算、层级策略、动效方案。如果产品背景允许，提供 2–3 种不同方向。**暂停并取得用户批准后，才能撰写 DESIGN.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 的 Quick Links 中添加 - [设计语言](DESIGN.md)（如果代码库有 AGENTS.md 但没有 Quick Links，则创建该部分；如果没有 AGENTS.md，则跳过）。

流程（按顺序）

1. 阶段 0 审核与分类（检查上方清单）
2. 仅限模式 C：撰写提案、提交提案，并等待批准
3. 使用 references/design-md-template.md 作为结构编写 DESIGN.md——内容根据证据填写（模式 A/B），或根据已批准的提案填写（模式 C）
4. 根据 references/skill-frontend-design.md 原文创建 .agents/skills/frontend-design/SKILL.md（去掉模板前言）；如果仓库已有同等的设计技能，则跳过
5. 在 AGENTS.md 的 Quick Links 中添加 DESIGN.md 链接
6. 执行下方的验证检查
7. 报告：所选模式及原因、创建的文件、文档与代码之间发现的矛盾，以及保留的预先存在文档中的规则

DESIGN.md 编写规则

• 引用真实文件。 文档中提及的每个令牌、工具类、字体和组件模式都必须链接到定义它的文件
• 明确限制。 出色的设计语言大多依赖克制——明确写出限制（“每个视图只用一组强调色搭配”“每页最多一个展示字体场景”），因为 Agent 更容易遵循明确的限制，而不是模糊的感觉
• 加入一句话概述。 在靠近文档开头的位置放置一个块引用，用一段话概括整套设计语言，方便 Agent 将其应用到其他界面
• 以逐页检查清单结尾，列出可验证的项目，方便 Agent 自行检查
• 用尺寸替代形容词。 “rounded-3xl 卡片、rounded-full CTA”胜过“圆角宽大”
• 在仓库的令牌系统适用之处，始终优先使用语义令牌，而非硬编码值；明确列出获准的例外情况

限制

• 绝不为了匹配 DESIGN.md 而重新设计现有组件。 文档用于描述或提出建议，并不授权重构。如果用户希望界面符合文档要求，那是另一个需要明确提出的任务
• 在模式 A 和 B 中，记录设计语言时不得“改进”它；改进建议应放在末尾明确标注的“待探讨问题”部分
• 除非已在本仓库中验证，或已在模式 C 提案中获批，否则不得将其他产品的设计语言（字体、配色、视觉元素）复制到 DESIGN.md
• 准确的短文档胜过令人印象深刻的长文档——如果设计文档有误，信任它的 Agent 就会自信地构建错误的 UI
• 遵循仓库的 Markdown 语气和格式

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

• DESIGN.md 中引用的每个文件路径都指向现有文件
• 文档中提及的每个令牌、工具类和字体都存在于代码库中（使用 grep 搜索）
• 模式 A/B：文档中的规则与实际表现最完善的界面不存在冲突
• 模式 B：预先存在的文档中的每条独有规则都保留在合并结果中（逐项比较）
• 模式 C：文档符合已批准的提案；提案文件存在于 docs/plans/ 中
• AGENTS.md 中的链接有效
• DESIGN.md 末尾的检查清单只包含 Agent 可通过代码验证的项目

完成标准

• 在本仓库中构建 UI 的 Agent 无需离开 DESIGN.md 就能了解“使用什么字体、令牌、圆角、阴影和动效”，并且只需从 AGENTS.md 点击一次即可到达
• 用户现有的设计决策得到保留——没有任何内容被覆盖，任何新的设计方向都已获得明确批准
• 已安装可移植的 frontend-design 设计技能
• 文档中的每项陈述都有证据支持（或获得批准），且验证检查全部通过