尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

DESIGN.md:缺失的设计手册——用 Markdown 给 AI 编码 Agent 补上规范驱动开发这一环

DESIGN.md:缺失的设计手册——用 Markdown 给 AI 编码 Agent 补上规范驱动开发这一环 1. 为什么 AI 编码 Agent 总在第三天开始“跑偏”如果你用 AI 编码 Agent 写过前端大概率经历过这个曲线第一天惊艳第二天顺手第三天开始怀疑人生。Agent 忘了你用的是 pnpm转头给你装 npm 依赖上一轮定好的卡片圆角这一轮变成了直角你明明说过主色是深蓝它给你整出一个紫色渐变按钮。这不是模型变笨了而是它每次新会话开始时对上一轮的记忆非常有限。AGENTS.md 解决了一部分问题。它把构建命令、测试框架、代码约定、Git 工作流这些“怎么造”的规则固化下来让 Agent 不用每次重新扫描仓库。但它管的是工程侧的事。你问它“辅助按钮的 hover 状态是什么颜色”“标题和正文的行高比例是多少”它答不上来因为这些属于视觉与交互决策不在它的职责范围内。于是就有了 DESIGN.md 这个补位角色。它是一份用 Markdown 写的设计规范专门约束 Agent 在生成 UI 时该用什么颜色、字号、间距、动效和边界条件。AGENTS.md 告诉 Agent 怎么构建DESIGN.md 告诉它怎么“看”。两者配合才构成完整的规范驱动开发闭环。这篇就交付一套可复制的 DESIGN.md 骨架、AGENTS.md 的引用配置以及让 Agent 读取后按规范产出、再逐条校验的验证动作。2. 前置准备TaoToken 接入与项目结构在写规范之前先把执行环境搭好。我习惯用 TaoToken 作为统一的模型接入层它兼容 OpenAI 风格的接口配置简单适合在 Agent 工作流里做模型调用。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。第一步去控制台创建 API Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面生成一个密钥复制保存。这个 Key 后面会写进环境变量不要硬编码进仓库。第二步确认项目根目录结构。一个适合规范驱动开发的最小结构长这样my-app/ ├── AGENTS.md # 工程侧规则Agent 的主入口 ├── DESIGN.md # 设计侧规范视觉与交互约束 ├── design-tokens.md # 可选拆分的原始 token 值 ├── components.md # 可选组件交互规范 └── src/第三步配置环境变量。在终端里设置或者写进.env.local记得加进.gitignoreexport TAOTOKEN_API_KEYsk-你的密钥 export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Claude Code 这类工具它走自己的CLAUDE.md约定可以在里面引用 AGENTS.md 保持说明可移植。模型对话调试可以直接用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 验证连通性。3. 可复制的 DESIGN.md 骨架下面这份骨架可以直接拿去改。核心思路是每个部分都带语义角色而不是丢一堆裸值。Agent 需要知道“这个颜色是干什么用的”而不只是“这个颜色长什么样”。3.1 视觉主题与氛围放在文件最顶部用两三句话定调。这段文字会在 Agent 遇到规范未覆盖的边缘情况时指导它的概率性决策。# DESIGN.md ## Visual Theme 干净、克制的现代界面以强排版层级和充足留白为核心。 避免装饰性阴影和渐变强调内容密度与可读性。 整体气质偏工具型产品而非营销落地页。写“干净现代”和写“粗野主义、强排版焦点、视口密度上限 60%”是两回事。后者能让 Agent 产出有身份感的界面前者只会让它回退到通用 Material 风格。3.2 语义化颜色调色板不要只列十六进制。按功能角色定义命名从系统到类再到角色## Color Palette - color.bg.surface → #FFFFFF — 标准容器默认背景 - color.bg.surface-raised → #F8FAFC — 抬升卡片与模态背景 - color.fg.primary → #0F172A — 浅色表面上的主文本 - color.fg.muted → #64748B — 次要文本满足 WCAG 对比度 - color.action.primary → #2563EB — 主 CTA 按钮与链接 - color.action.danger → #DC2626 — 破坏性操作与错误态color.bg.surface这个命名让 Agent 理解意图它意味着“默认容器背景”而不是“碰巧是白色的颜色”。主题切换时Agent 能智能替换值因为它知道角色。把可访问性约束直接写进 token 定义Agent 无需额外指令就能执行。3.3 排版层级构建不可变的层级表每个文本元素映射到特定条目杜绝 Agent 幻觉出任意字号## Typography - Display → Inter, 700, 48px, line-height 1.1, letter-spacing -0.02em - H1 → Inter, 700, 36px, line-height 1.2, letter-spacing -0.01em - H2 → Inter, 600, 28px, line-height 1.3, letter-spacing 0 - Body → Inter, 400, 16px, line-height 1.6, letter-spacing 0 - Caption → Inter, 400, 12px, line-height 1.4, letter-spacing 0.01em3.4 间距 Scale定义数学间距系统并坚持## Spacing Scale Base unit: 4px - space-1 → 4px — 相关元素间的紧凑间隙 - space-2 → 8px — 默认行内间距 - space-3 → 12px — 组件内部 padding - space-4 → 16px — 标准区块间隙 - space-6 → 24px — 容器 padding - space-8 → 32px — 主要区块分隔 - space-12 → 48px — 页面级呼吸空间3.5 Dos 与 Donts回报最快的部分对大量 Agent 配置的分析显示告诉 Agent 不要做什么比告诉它要做什么更有效。明确的禁止创造刚性边界把模型的输出空间收窄到定义的沙箱里。## Dos - 页面级布局用 CSS Grid - 组件级对齐用 Flexbox - 兄弟元素间距优先用 gap 而非 margin - 所有设计 token 用 CSS 自定义属性 ## Donts - NEVER 使用 !important - NEVER 使用内联样式 - NEVER 动画 width、height、margin、box-shadow - NEVER 使用 transition: all逐条列出属性 - NEVER 给基础平面元素加阴影 - NEVER 用 px 写字号用 rem - NEVER 嵌套超过 3 层 CSS 选择器3.6 Motion 规范没有约束时Agent 经常给 width、height 这类昂贵布局属性做动画触发布局重绘移动端直接掉帧。规范要无情地规定## Motion Tokens - motion-micro → 75ms — 按钮按下、开关切换 (ease-out) - motion-short → 150ms — hover 态、输入聚焦 (ease-in-out) - motion-medium → 200ms — 页面交叉淡入、模态进入 (ease-out) - motion-long → 400ms — 侧边栏展开、下拉 (ease-in-out) ### Hard Rules - 只动画 transform 和 opacityGPU 加速属性 - NEVER 使用 transition: all - 所有动画 MUST 尊重 prefers-reduced-motion 媒体查询3.7 用文本图表教 Agent 看架构现代 LLM 能处理图像但把 PNG 架构图喂进去比文本替代方案更贵、更不可靠。解决方案是直接嵌入 Mermaid 语法它完全由文本字符构建能和 token 定义并排Agent 同时处理结构和样式。组件层次用流程图flowchart TD App -- Header App -- MainContent App -- Footer MainContent -- Sidebar MainContent -- ContentArea ContentArea -- ArticleList ContentArea -- Pagination交互组件生命周期用状态图stateDiagram-v2 [*] -- Idle Idle -- Hover: mouseenter Hover -- Active: click Active -- Loading: async request Loading -- Success: response ok Loading -- Error: response fail Success -- Idle: timeout Error -- Idle: dismissMermaid 块在 Git 里显示可读 diff而图片是不透明二进制。有人更新状态转换时PR 能看清改了什么Agent 下次检索时自动拿到新架构。4. 把 DESIGN.md 接进 AGENTS.md 工作流DESIGN.md 不孤立运行。AGENTS.md 坐在项目根目录当主路由器当 Agent 收到 UI 相关任务时明确告诉它先获取并解析 DESIGN.md。在 AGENTS.md 里加这样一段引用## Design System 任何涉及 UI、样式、布局、交互的任务在生成代码前 MUST 先读取并解析 DESIGN.md。 所有颜色、字号、间距、动效值 MUST 来自 DESIGN.md 中定义的 token禁止自行发明数值。 若 DESIGN.md 未覆盖某决策遵循其 Visual Theme 部分的整体方向并在输出中标注该假设。如果 DESIGN.md 增长到几千 token 以上考虑拆分design-tokens.md放原始值components.md放交互规范AGENTS.md 按任务类型选择性引用。一些团队把这些输入向量库让 RAG 管道只检索相关部分而不是把整个文件塞进上下文窗口。5. 验证让 Agent 按规范产出并逐条校验规范写完不算完得验证 Agent 真的读了、真的照做了。下面是一套可执行的验证动作。5.1 发一个受约束的生成请求用 TaoToken 的接口发一个 UI 生成任务把 DESIGN.md 作为上下文注入。这里用 curl 演示curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [ { role: system, content: 你是前端工程师。生成任何 UI 代码前必须遵守 DESIGN.md 中的全部 token 与 Don\ts 规则。 }, { role: user, content: 读取 DESIGN.md生成一个带主按钮和辅助按钮的卡片组件。只输出代码。 } ] }5.2 逐条校验产出拿到代码后对照 DESIGN.md 逐条检查。可以写一个简单的校验脚本把常见违规模式扫一遍# 检查是否用了 !important grep -n !important output.css echo 违规使用了 !important # 检查是否用了 transition: all grep -n transition: all output.css echo 违规使用了 transition: all # 检查是否动画了布局属性 grep -nE transition:.*(width|height|margin|box-shadow) output.css echo 违规动画了布局属性 # 检查字号是否用了 px grep -nE font-size:\s*[0-9]px output.css echo 违规字号用了 px5.3 成功结果长什么样一份合格的产出应该满足颜色值全部来自color.*token没有裸十六进制字号全部用rem间距值落在 spacing scale 上动效只碰transform和opacity没有!important和内联样式。如果校验脚本全部静默通过说明 Agent 确实按规范产出了。实测下来把 DESIGN.md 接进工作流后Agent 生成界面的返工率明显下降尤其是颜色和间距这两类“看起来不对劲”的问题。踩过的坑是一开始 DESIGN.md 写得太抽象Agent 还是乱来后来把 Donts 写具体、把 token 命名带语义效果才稳定。6. 常见错误排查Agent 完全无视 DESIGN.md。先确认 AGENTS.md 里的引用路径正确且任务描述里明确提到 UI 相关。有些工具需要显式在 prompt 里说“读取 DESIGN.md”光靠 AGENTS.md 路由不一定触发。Agent 读了但用错 token。多半是 token 命名不够语义化。把color-blue-500改成color.action.primaryAgent 才能理解角色而非外观。动效还是卡顿。检查 Hard Rules 是否写进了 DESIGN.md以及 Agent 是否真的遵守。可以在校验脚本里加一条对will-change滥用的检查。上下文窗口爆了。DESIGN.md 太大时拆分成多个文件用 RAG 按任务检索。别把整个设计系统每次都塞进去。Mermaid 图没被解析。确认代码块标注了mermaid语言且 Agent 的解析器支持。不支持的话退化成缩进列表描述状态转换。如果你在接入或排障时遇到问题可以去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 检查密钥状态接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。需要长期跑编码 Agent、做多轮 UI 生成的话Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 更适合持续性的规范驱动开发场景。想先验证模型对 DESIGN.md 的理解能力用模型对话 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 快速试几轮就行。从最痛的地方开始写你的 DESIGN.md先定视觉主题、颜色和排版三块在 AGENTS.md 里加一句引用然后发一个受约束的生成请求用校验脚本扫一遍产出。第一周你就能感觉到差别——Agent 不再每次重新猜你的设计意图而是照着同一份简报干活。
返回列表