主题
03-04 · 设计系统 · DESIGN.md（awesome-design-md）
VoltAgent 团队整理的 awesome-design-md 是一份 DESIGN.md 模板集：把 Apple、Stripe、Notion、Linear、Vercel… 这些品牌的设计系统抽成一个 markdown 文件，直接丢进项目，让 AI Agent 生成对应风格的 UI。
一、它解决了什么
让 Agent 写前端代码，最大的痛点：
- "请用现代风格做一个登录页" → 它给你一个 2018 年的页面
- "请参考 Stripe 的风格" → 它脑补一个 90% 像但 10% 跑偏的版本
- 每次新建项目都要重新约定 token、配色、字体
DESIGN.md 给出一个标准答案：把"什么是 Stripe 风格 / 什么是 Linear 风格"压缩成一份 LLM 友好的文档。Agent 只要读一遍就能稳定复现风格。
二、仓库速览
- 仓库：https://github.com/VoltAgent/awesome-design-md
- Star 数：69k+（前端类项目里的顶流）
- 内容：80+ 个品牌的 DESIGN.md，覆盖科技、金融、电商、内容、媒体
| 类别 | 代表品牌 |
|---|---|
| Tech / SaaS | Stripe、Linear、Vercel、Supabase、Notion |
| 内容 / 媒体 | The New York Times、Medium |
| 电商 | Apple、Nike |
| 金融 | Robinhood、Wise |
| 中性 / 极简 | Tailwind UI、Shadcn |
三、用法（公司标准流程）
Step 1：选一份 DESIGN.md
例如做一个 SaaS 产品，可以从 Stripe / Linear / Vercel 里选。
bash
# clone 仓库
git clone https://github.com/VoltAgent/awesome-design-md.git ~/projects/awesome-design-md
# 找到对应文件
ls ~/projects/awesome-design-md/designs/
# 选一份，比如 stripe.mdStep 2：丢到你的项目根目录
bash
cp ~/projects/awesome-design-md/designs/stripe.md /path/to/your/project/DESIGN.md必须命名为
DESIGN.md（大写 D），放在项目根目录。这是 Claude Code / Windsurf 默认会扫描的文件名。
Step 3：在 CLAUDE.md / AGENTS.md 里引用
markdown
# CLAUDE.md / AGENTS.md
## 设计规范
本项目所有 UI 必须严格遵守 `./DESIGN.md` 中的设计系统：
- 颜色 token 必须使用 DESIGN.md 中定义的变量名
- 间距 / 圆角 / 字号必须使用 DESIGN.md 中的尺度
- 组件实现风格参考 DESIGN.md 中的示例代码Step 4：让 Agent 生成 UI
> 帮我用 React + Tailwind + shadcn/ui 实现一个 dashboard，包含侧边栏、顶栏、卡片网格。严格按照 DESIGN.md 的规范执行。它会：
- 读 DESIGN.md
- 抽取 token（颜色、字号、间距）
- 生成对应的
tailwind.config.ts/ CSS variables - 用 token 实现组件
四、二次定制：写公司专属的 DESIGN.md
社区版的 DESIGN.md 是个起点，你应该基于它改一份公司自己的。
4.1 推荐结构
markdown
# 上海奇点砚 · 设计系统
## Brand Identity
- 品牌定位：[一句话]
- Tone：克制、专业、技术感
## Color Tokens
### Primary
- primary-50: #f5f8ff
- primary-500: #2b5cff
- primary-900: #0a1f6b
### Semantic
- success: #16a34a
- warning: #f59e0b
- danger: #ef4444
### Neutral
- gray-50 … gray-900
## Typography
- font-sans: "Inter", "PingFang SC", system-ui
- font-mono: "JetBrains Mono"
- 标题尺度：text-3xl / text-2xl / text-xl
- 正文：text-base 16px / line-height 1.6
## Spacing
- 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 (px)
## Radius
- sm: 6px
- md: 10px ← 默认
- lg: 16px
## Shadow
- subtle: 0 1px 2px rgba(0,0,0,0.04)
- card: 0 4px 12px rgba(0,0,0,0.06)
## Components
### Button（带示例代码）
### Card
### Form
### Modal
…
## Forbidden
- 不使用 emoji 作为图标
- 不使用纯黑（#000）作为正文颜色，统一 gray-9004.2 把它沉淀成公司 Skill
按 02-核心方法论/04-Skills详解.md 的方法，包成 qdy-design-system Skill：
~/.claude/skills/qdy-design-system/
├── SKILL.md ← 触发条件："写前端"、"做 UI"
└── DESIGN.md ← 你刚写的设计系统之后每个新项目，不再需要复制 DESIGN.md，Agent 会自动加载这个 Skill。
五、常配的前端工具栈（公司默认）
| 类别 | 默认选择 |
|---|---|
| 框架 | React 19 + Vite（小项目）/ Next.js 15（中大型） |
| 样式 | Tailwind CSS v4 |
| 组件库 | shadcn/ui（强烈推荐） |
| 图标 | Lucide |
| 表单 | react-hook-form + zod |
| 状态 | Zustand（首选）/ TanStack Query 缓存（服务端状态） |
| 数据请求 | TanStack Query |
| 动效 | Framer Motion |
shadcn/ui 是当前公司默认的组件方案。它的特点是组件代码会被 copy 进你的项目，方便配合 DESIGN.md 二次改造。详细栈用法见 03 · 前端 · React + Vite。
六、参考资料
继续 → 05 · 依赖管理与版本规范