【技术干货】用 design.md 驯服 AI 生成前端：从 Awesome Design 到工程化落地实践

摘要本文围绕 GitHub 仓库 Awesome Designdesign.md 方案系统拆解如何用“可读的设计系统描述”约束 AI Agent 生成前端 UI解决常见的风格漂移、视觉割裂问题。文章从原理到实战给出接入 AI 接口基于 xuedingmao.com的完整 Python 示例并结合 agents.md、design.md 的双文件策略构建可复用、可扩展的 AI 前端工作流。一、背景介绍AI 会写前端但不会“做设计”当前大模型 / AI Agents 生成前端代码已经不稀奇了React 组件、Tailwind 样式、Next.js 页面一句 prompt 就能拉出来。但实际落地时大家普遍会遇到几个问题结构能用但视觉“一盘散沙”Hero 区块还不错往下滚间距随机、卡片样式杂乱、按钮像从别的站拷贝来的整个页面像“5 次不同 prompt 拼接”的结果提示词难以精确控制视觉“做得简洁现代一点”“像 Stripe 一点”这类描述对模型来说过于模糊每次改动都要重新堆长 prompt成本高且不可复用架构规则 设计规则混在一起在一个 prompt 里同时塞技术栈要求Next.js / Tailwind / TS…行为逻辑路由、状态管理视觉风格色板、字体、间距文案语气模型极易“注意力分散”导致 UI 风格漂移视频中提到的 Awesome Design 仓库以及 design.md 方案本质是在解决一个问题如何把“设计系统”变成模型可理解、可复用的文本规范让 AI 生成的 UI 一致、可控、工程化。二、核心原理用 design.md 把“脑中的设计语言”写给模型看2.1 design.md 到底是什么design.md 本质是一个结构化的 Markdown 文档以 AI Agent 易于读取的方式描述完整的设计系统。典型内容包括视觉基调Visual Mood极简 / 高对比 / 暗色优先 / 极客风 等色彩系统Color Palette主色 / 辅助色 / 背景 / 边框 / 状态色Success / Warning / Error排版规则Typography Rules主字体 / 备选字体标题层级H1/H2/H3字号、行高、字重正文、辅助文案、代码字体组件样式Component Styling按钮主按钮 / 次按钮 / 文字按钮卡片阴影、圆角、边框策略标签、输入框、表单、导航栏等空间与布局Spacing Layout基础间距单位4/8/12/16…栅格系统、内容最大宽度区块之间的层级关系与留白层次与动效Depth Interaction阴影层级、hover/active 状态悬浮卡片、模态框的层级规范响应式行为Responsive Behavior不同断点的布局重排规则移动端优先 / 桌面端优先策略设计护栏Design Guard Rails禁止使用的颜色、动效限制同时出现的组件组合避免的视觉反模式如过多阴影、渐变堆砌这一点与我们常见的设计系统文档类似只是表达方式从设计稿 / Figma 文档变成了更“LLM 友好”的 Markdown 文本。2.2 design.md 与 agents.md 的职责分离仓库 README 中有一个非常关键的设计agents.md定义项目如何被构建技术栈Next.js React Tailwind TypeScript文件结构pages / app 路由、组件组织代码规范ESLint、命名约定业务行为比如 Dashboard 如何调用 APIdesign.md定义项目看起来应该是什么样上面提到的视觉基调、组件样式、布局规则等这种拆分带来的好处提示词变短、变稳定Prompt 不再反复描述“UI 要干净现代颜色如何如何”而是简单一句“遵循根目录的 design.md 进行视觉实现”风格可复用同一套 design.md 可以作用于多个项目适合团队级别的“品牌设计系统”落地避免 UI 漂移多轮迭代时模型总是回头读同一个 design.md二次 refinement 不会越改越跑偏2.3 Awesome Design 仓库的价值Awesome Design 做的事情是基于知名网站Vercel、Linear、Stripe、Raycast、Supabase、Notion…为每种风格准备一套完整的design.mdpreview.htmlpreview-dark.html这意味着你可以在使用前先打开 preview.html 看一眼视觉大致方向再把对应 design.md 放到你的项目里作为视觉“单一事实来源Source of Truth”它不是魔法也不是一键克隆网站而是提供一套“设计纪律design discipline”的文本模板让 AI 生成 UI 时有明确的依托。三、实战演示用 Python 薛定猫 AI API 驱动 Agent 读取 design.md 生成前端下面构造一个不依赖 Verdant 的通用工作流用你自己的 Agent Awesome Design 的 design.md 完成一次 Landing Page 生成并给出可直接运行的 Python 示例。3.1 前端项目准备思路你可以用任意栈Next.js、Vite、Astro 等流程类似初始化项目例如 Next.js从 Awesome Design 仓库里挑一个喜欢的设计风格拷贝其design.md把design.md放在项目根目录用 AI Agent通过 API 调用读取design.md你的需求描述比如“生成一个 AI SaaS Landing Page”约定代码格式React Tailwind / 纯 HTML 等让 Agent 输出完整页面代码写入项目文件下面重点展示第 4、5 步如何用 xuedingmao.com 的 OpenAI 兼容 API 驱动这个 Agent。3.2 使用薛定猫 AI 的原因技术选型视角在多模型前端生成场景下有几个非常实际的需求需要频繁试验不同模型Claude 4.6/GPT 5.4/Gemini 3 Pro 等希望新模型上线时能尽快用上后端接入成本要低不想为每个厂商写一套 SDK薛定猫 AIxuedingmao.com的特点刚好比较适合这种需求聚合 500 主流大模型含 GPT-5.4、Claude 4.6、Gemini 3 Pro 等单一接口切换模型新模型实时首发适合追新能力的开发者提供 OpenAI 兼容模式就是 URL KEY model代码层面基本按 OpenAI 写就行这样我们可以在同一套“design.md prompt”基础上横向对比不同模型生成 UI 的质量根据效果和成本选择最适合自己团队的模型而不用大改代码3.3 完整 Python 示例读取 design.md 生成 React Landing Page下面是一个完整可用的示例假设你本地有一个前端项目目录./my-landing里面有从 Awesome Design 仓库拷贝来的design.md你希望生成src/App.tsx作为主页面Vite React 为例你使用薛定猫 AI 的 OpenAI 兼容 API模型选用claude-sonnet-4-6importosimporttextwrapfromtypingimportOptionalfromopenaiimportOpenAI# # 配置区# # 薛定猫 AI 平台的 API Key从 xuedingmao.com 用户中心获取XDM_API_KEYos.environ.get(XDM_API_KEY,YOUR_XUEDINGMAO_API_KEY)# OpenAI 兼容的 Base URLXDM_BASE_URLhttps://xuedingmao.com/v1# 使用的模型这里按要求默认使用 claude-sonnet-4-6MODEL_NAMEclaude-sonnet-4-6# 前端项目根目录包含 design.mdPROJECT_ROOT./my-landing# 生成文件路径以 Vite React TS 项目为例OUTPUT_FILEos.path.join(PROJECT_ROOT,src,App.tsx)# # 帮助函数# defload_design_md(project_root:str)-Optional[str]: 从项目根目录加载 design.md 内容。 design_pathos.path.join(project_root,design.md)ifnotos.path.exists(design_path):print(f[WARN] design.md not found at{design_path})returnNonewithopen(design_path,r,encodingutf-8)asf:returnf.read()defbuild_system_prompt()-str: 构造系统提示词 - 定义你的 Agent 行为 - 指定技术栈和输出要求 # 这里采用 Vite React TypeScript Tailwind 的组合你可以根据项目修改system_prompttextwrap.dedent( 你是一个资深前端工程师 设计系统专家负责根据项目的 design.md 规范 生成高质量、可运行的 React TypeScript 组件代码Vite 项目结构。 关键要求 1. 使用 React 函数组件 TypeScripttsx。 2. 使用 Tailwind CSS 进行样式控制不要写内联 style。 3. 遵循项目根目录 design.md 中描述的 - 视觉基调 - 色彩系统 - 字体与排版层级 - 组件样式按钮、卡片、标签等 - 间距和布局原则 - 响应式行为 - 设计护栏 4. 输出必须是一个完整的 React 组件文件 App.tsx - 默认导出一个 App 组件export default function App() { ... } - 不要包含多余说明性文本只输出 TypeScript/JSX 代码。 5. 确保结构具备典型 Landing Page 的主要区块 - Hero主视觉区域 - 特性/优势板块Feature Section - 客户或使用场景简介 - 最终 Call-to-ActionCTA 6. 保持代码整洁、有注释但注释不要过多以免影响可读性。 ).strip()returnsystem_promptdefbuild_user_prompt(design_md:str)-str: 构造用户提示词附带 design.md 内容。 user_prompttextwrap.dedent(f 下面是项目根目录中的 design.md 内容请完整阅读并据此实现页面 markdown{design_md} 需求 - 为一个 AI SaaS 产品生成 Landing Page 界面 - 产品定位帮助开发者用 AI 生成高质量前端代码和 UI - 目标受众前端工程师、全栈工程师、小型团队 - 风格与 design.md 保持一致请严格遵循色彩、排版、组件规范 - 页面应为单页结构由 App.tsx 组件渲染 - 包含导航栏、主视觉、特性列表、产品亮点、简单价格/方案概览、最终 CTA 区域 - 需要考虑桌面端和移动端的响应式布局通过 Tailwind 实现 - 不要输出解释或额外 Markdown只输出完整的 App.tsx 源代码。 ).strip()returnuser_promptdefgenerate_landing_page(): 主流程 1. 读取 design.md 2. 通过薛定猫 AI 的 OpenAI 兼容接口调用大模型 3. 将生成的 App.tsx 写入项目目录 design_mdload_design_md(PROJECT_ROOT)ifnotdesign_md:raiseFileNotFoundError(design.md not found. Please put design.md in project root.)# 初始化 OpenAI 兼容客户端clientOpenAI(api_keyXDM_API_KEY,base_urlXDM_BASE_URL)system_promptbuild_system_prompt()user_promptbuild_user_prompt(design_md)print([INFO] Calling model to generate App.tsx ...)# 调用大模型兼容 Chat Completions 风格接口responseclient.chat.completions.create(modelMODEL_NAME,messages[{role:system,content:system_prompt},{role:user,content:user_prompt},],temperature0.3,# 降低随机性提高确定性和可复现性max_tokens4096,)contentresponse.choices[0].message.content# 简单清洗有些模型可能意外包裹 tsx 代码块这里做一次去除ifincontent:# 尝试提取代码块内部内容partscontent.split()# 代码通常在第 2 段或第 3 段code_candidates[pforpinpartsifexport default functioninporexport defaultinp]ifcode_candidates:contentcode_candidates[0]# 确保输出目录存在os.makedirs(os.path.dirname(OUTPUT_FILE),exist_okTrue)withopen(OUTPUT_FILE,w,encodingutf-8)asf:f.write(content)print(f[INFO] App.tsx generated at:{OUTPUT_FILE})if__name____main__: 使用方式 1. 在 xuedingmao.com 获取 API Key - 设置环境变量export XDM_API_KEYyour_key 2. 准备前端项目并在项目根目录放置 design.md - e.g. ./my-landing/design.md 3. 运行本脚本 - python generate_landing.py 4. 启动 Vite 项目查看效果 - cd my-landing npm run dev generate_landing_page()这个脚本实现了一个“轻量级 Verdant 思路”的最小版本委托模型自己阅读design.md通过系统提示词 用户需求组合生成符合设计系统的前端页面代码design.md作为视觉单一事实来源后续你可以继续发起第二轮请求进行 refinement如果你希望做多轮 refinement可以在第一次生成后保留模型会话传入所有历史 messages每次只附加新的“优化指令”而不要重复塞 design.md改为一句“仍然遵循根目录 design.md”。四、注意事项与实践经验4.1 不要做“懒惰克隆”Awesome Design 里很多风格都是基于知名网站Vercel、Linear、Stripe…攒得非常好用。但建议做法是借用设计规范不要克隆内容结构和品牌替换文案、信息架构调整产品叙事和品牌细节从法律和产品差异化角度这一点都非常重要4.2 结果质量仍然依赖模型与提示即使 design.md 很详细生成质量仍然取决于所选模型的指令遵从能力与代码生成能力system和userprompt 的清晰度项目结构你是否清楚告诉它文件要放在哪、如何组织实践中建议第一轮输出看“大局”结构和风格是否跑偏第二轮开始再做细化提示精简 Hero 文案减少装饰性元素调整卡片平面化程度检查移动端布局表现并修正4.3 复杂度 vs 需求匹配对于简单内部工具如内部报表、小脚本 UI直接让模型“随便来一个好用的 UI”即可没必要上完整 design.md对于以下类型项目则非常推荐Landing Page面向客户的后台 / DashboardDocs 站点对外 Demo / PoC4.4 多模型实验风格遵循 vs 创造性平衡利用薛定猫 AI 的多模型聚合特点你可以用同一份design.md 同一份 prompt分别调用 Claude 系列、GPT 系列、Gemini 系列对比哪个模型在遵循 design.md 的同时代码质量更好哪个模型在响应式布局、Tailwind 实践上更稳这种 A/B 测试模式是在单厂商 API 里很难低成本实现的。五、技术资源与工具推荐5.1 Awesome Design 仓库关键词awesome design.md/awesome-design主要内容超过 50 套基于真实网站的设计系统文本每套包含design.md、preview.html、preview-dark.html使用建议先在浏览器打开预览 HTML选中与自己产品气质接近的一套拷贝 design.md结合自己品牌做定制化修改5.2 技术选型从纯技术选型的角度xuedingmao.com对本文工作流的价值在于聚合 500 主流大模型GPT-5.4、Claude 4.6、Gemini 3 Pro 等主力模型统一接入适合做跨模型对比和性能评估新模型快速可用前沿模型上线后无需等待各家 SDK 更新对需要尝鲜和追最新能力的前端 / 全栈开发者非常友好统一 OpenAI 兼容接口base_url api_key model即可使用原有基于 OpenAI SDK 的项目几乎零改动迁移对多模型集成和切换成本极低在“AI 驱动前端生成”的场景下能稳且快地试验不同模型比单一模型依赖更有工程价值。总结Awesome Design design.md 方案并没有引入什么“新魔法”它做的事非常朴素把原本在设计师脑海、Figma、截图里的“设计语言”转写成一个结构化 Markdown 文本让 AI Agent 真正能读懂并遵循配合 agents.md 将架构规则与视觉规则解耦再通过类似本文的 Python 薛定猫 AI API 调用构建起这样一条可复制的工作流打开项目放入 design.md在 Agent 的系统提示中声明“所有 UI 必须遵循 design.md”用统一的 API 调用模型生成初版 UI在同一 design.md 约束下做多轮 refinement而不是一遍遍重写长 prompt如果你已经厌倦了那种“上半屏还行、往下滚就散架”的 AI 生成页面这套工作流非常值得在团队里试一试。#AI #大模型 #Python #机器学习 #技术实战