1. 为什么 AI 写的前端总是“上半屏惊艳往下滚就散架”如果你最近用 Claude、GPT 或者 Gemini 生成过前端页面大概率经历过这种落差Hero 区域看着还行往下滚动卡片圆角一会儿 8px 一会儿 16px按钮颜色从品牌蓝跳到紫色间距忽大忽小整个页面像是五个人分别用五套设计稿拼出来的。这不是模型能力不行而是我们给它的输入里设计规则和技术规则混在一起注意力被稀释了。我试过把“用 Next.js Tailwind TypeScript做一个简洁现代的 SaaS 落地页主色用蓝色卡片要有阴影按钮要圆角”这一长串塞进一个 prompt结果模型确实生成了代码但每次重新生成色值、圆角、阴影都在漂移。原因很简单大模型在单次生成里要同时处理技术栈、业务逻辑、视觉风格、文案语气四类信息任何一类描述不够结构化它就会“自由发挥”。解决思路其实不复杂把设计系统从 prompt 里抽出来变成一个模型每次都会读的独立文件。这就是 design.md 方案的核心——用一份结构化的 Markdown 描述视觉基调、色彩、排版、组件样式、间距、响应式规则和设计护栏让 AI Agent 在生成 UI 时有一个稳定的“单一事实来源”。配合 agents.md 把技术栈和代码规范单独拆出去模型每次只需要读两个文件就能在风格上保持一致。这篇文章会带你从零走一遍先准备 design.md 和 agents.md 双文件再用 TaoToken 统一 Key 接入 AI 工具最后用一段可复制的 Python 脚本验证生成效果并给出常见报错的排查方法。目标很明确——让前端团队把 AI 产出稳定纳入工程化流程而不是每次靠运气。适合谁看正在用 AI 辅助写前端、但被风格漂移困扰的工程师想把设计系统落地到 AI 工作流的前端团队以及想用统一 Key 管理多模型调用的开发者。下面所有配置和代码都可以直接复制运行。2. TaoToken 统一 Key 接入一次配置多模型切换在讲 design.md 模板之前先解决一个工程化前提AI 工具的接入方式要统一。如果你同时用 Claude Code、Cline、Codex 或者自己写的 Python 脚本每个工具一套 Key、一套 Base URL管理成本会很高而且做多模型对比时改代码很麻烦。TaoToken 的思路是提供一个统一的 API 入口你只需要维护一个 Key就能在多个模型之间切换。2.1 获取 Key 和确认 Base URL先到 TaoToken 官网注册并进入控制台在 API Keys 页面创建一个 Key。建议按项目或按工具命名比如design-md-frontend方便后续排查是哪个工具在调用。创建后立刻复制保存页面刷新后不会再完整显示。Base URL 统一使用https://taotoken.net/api注意这个地址不带任何查询参数。模型 ID 按你实际要用的填比如claude-sonnet-4-6、gpt-5.4、gemini-3-pro这类。三个要素记牢Base URL API Key Model ID后面所有工具配置都围绕这三件套。2.2 在 Claude Code 里配置Claude Code 支持通过环境变量或配置文件指定 API 端点。推荐用配置文件方式避免每次开终端都要 export。在项目根目录或用户目录下创建配置写入以下内容{ apiKey: sk-你的TaoTokenKey, baseURL: https://taotoken.net/api, model: claude-sonnet-4-6 }如果你用的是 Claude Code 的 settings 机制对应字段名可能是env下的ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY具体以你本地版本为准。配置完成后在项目里执行一次简单对话确认能正常返回再进入 design.md 环节。2.3 在 Cline / MCP 场景里配置Cline 这类 VS Code 插件通常在设置面板里选 “OpenAI Compatible”然后填三项Base URL 填https://taotoken.net/apiAPI Key 填你的 TaoToken KeyModel ID 填你要用的模型。如果你用 MCP 方式接入配置片段类似{ mcpServers: { taotoken: { command: npx, args: [-y, your-mcp-server], env: { OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_API_KEY: sk-你的TaoTokenKey, OPENAI_MODEL: claude-sonnet-4-6 } } } }注意 MCP 不要直连生产数据库这里只是模型调用不涉及数据写入。配置好后重启插件在对话里问一句“你现在用的是哪个模型”确认返回的模型 ID 和你填的一致。2.4 在 Codex auth.json 里配置如果你用 Codex 类工具认证信息通常放在~/.codex/auth.json。写入以下结构{ openai: { apiKey: sk-你的TaoTokenKey, baseURL: https://taotoken.net/api }, model: gpt-5.4 }保存后运行一次codex的测试命令确认没有 401。到这里你的统一 Key 就配好了接下来所有 AI 工具都走同一个入口做多模型对比时只需要改 Model ID不用动 Key 和 Base URL。3. design.md 与 agents.md 双文件模板可直接复制这一节是整篇文章的核心。design.md 负责“看起来什么样”agents.md 负责“怎么构建”两者职责分离模型读起来不会互相干扰。下面给出可直接复制到项目根目录的模板。3.1 design.md 完整模板# Design System ## Visual Mood - 极简、高对比、暗色优先 - 避免渐变堆砌避免过多阴影 - 整体气质专业、克制、工程感 ## Color Palette - Primary: #2563EB - Primary Hover: #1D4ED8 - Background: #0B0F19 - Surface: #111827 - Border: #1F2937 - Text Primary: #F9FAFB - Text Secondary: #9CA3AF - Success: #10B981 - Warning: #F59E0B - Error: #EF4444 ## Typography - 主字体: Inter, system-ui, sans-serif - 代码字体: JetBrains Mono, monospace - H1: 48px / 1.1 / 700 - H2: 32px / 1.2 / 600 - H3: 24px / 1.3 / 600 - Body: 16px / 1.6 / 400 - Caption: 14px / 1.5 / 400 ## Components ### Button - Primary: bg Primary, text white, rounded 8px, px 20px, py 10px - Secondary: bg transparent, border Border, text Text Primary - Hover: 使用对应 Hover 色过渡 150ms ### Card - bg Surface, border 1px Border, rounded 12px, p 24px - 不使用阴影靠边框区分层级 ### Input - bg Background, border Border, rounded 8px, px 12px, py 10px - Focus: border Primary ## Spacing - 基础单位 4px - 常用: 8 / 12 / 16 / 24 / 32 / 48 / 64 - 区块之间留白 64px卡片内 24px ## Layout - 内容最大宽度 1200px居中 - 栅格 12 列间距 24px - 移动端断点 768px桌面端 1024px ## Responsive - 移动端优先桌面端增强 - 768px 以下单列以上两列或三列 ## Design Guard Rails - 禁止使用未在 Color Palette 中定义的颜色 - 禁止同时使用阴影和边框表达层级 - 禁止使用超过两种字体 - 禁止在按钮上使用渐变这份模板的关键在于所有值都是确定的。模型不需要猜“蓝色大概是哪个蓝”它直接读#2563EB。你可以在 Awesome Design 仓库里挑一套接近你品牌气质的 design.md打开对应的 preview.html 看一眼视觉效果再替换成自己的色值和字体。3.2 agents.md 配置片段agents.md 管技术栈和代码规范和 design.md 分开# Agent Build Rules ## Tech Stack - Next.js 14 App Router - React 18 TypeScript - Tailwind CSS 3 - 不使用内联 style ## File Structure - 页面放 app/ 目录 - 组件放 components/ 目录 - 工具函数放 lib/ 目录 ## Code Rules - 函数组件 hooks - 组件文件名 PascalCase - 工具函数 camelCase - 每个组件文件默认导出 ## Behavior - 所有 UI 必须遵循根目录 design.md - 生成代码只输出文件内容不输出解释3.3 双文件如何配合在系统提示词里写一句“你是一个前端工程师构建规则遵循 agents.md视觉实现严格遵循 design.md。” 模型每次生成前会读这两个文件技术规则和视觉规则各归各的注意力不会被稀释。实测下来同一份 design.md 连续生成五次色值和圆角基本不会漂移剩下的差异主要在文案和布局细节上这属于可接受范围。4. 用 Python 验证生成效果从 design.md 到 App.tsx配置和模板都齐了现在用一段 Python 脚本走通完整流程读取 design.md调用 TaoToken 接口生成 App.tsx然后启动项目看效果。4.1 安装依赖pip install openai4.2 完整脚本import os import textwrap from openai import OpenAI API_KEY os.environ.get(TAOTOKEN_API_KEY, sk-你的TaoTokenKey) BASE_URL https://taotoken.net/api MODEL claude-sonnet-4-6 PROJECT_ROOT ./my-landing OUTPUT_FILE os.path.join(PROJECT_ROOT, src, App.tsx) def load_design_md(root): path os.path.join(root, design.md) if not os.path.exists(path): raise FileNotFoundError(fdesign.md not found at {path}) with open(path, r, encodingutf-8) as f: return f.read() def build_system_prompt(): return textwrap.dedent( 你是一个资深前端工程师。构建规则遵循项目根目录 agents.md 视觉实现严格遵循项目根目录 design.md。 使用 React 函数组件 TypeScript Tailwind CSS。 只输出完整的 App.tsx 代码不要输出解释。 ).strip() def build_user_prompt(design_md): return textwrap.dedent(f 下面是 design.md 内容请完整阅读并据此实现页面 markdown {design_md} 需求为一个 AI SaaS 产品生成 Landing Page 包含导航栏、Hero、特性列表、CTA 区域 响应式布局只输出 App.tsx 源代码。 ).strip() def main(): design_md load_design_md(PROJECT_ROOT) client OpenAI(api_keyAPI_KEY, base_urlBASE_URL) response client.chat.completions.create( modelMODEL, messages[ {role: system, content: build_system_prompt()}, {role: user, content: build_user_prompt(design_md)}, ], temperature0.3, max_tokens4096, ) content response.choices[0].message.content if in content: parts content.split() candidates [p for p in parts if export default in p] if candidates: content candidates[0] os.makedirs(os.path.dirname(OUTPUT_FILE), exist_okTrue) with open(OUTPUT_FILE, w, encodingutf-8) as f: f.write(content) print(fgenerated: {OUTPUT_FILE}) if __name__ __main__: main()4.3 运行与验证先准备一个 Vite React TS 项目把 design.md 和 agents.md 放到根目录然后export TAOTOKEN_API_KEYsk-你的TaoTokenKey python generate_landing.py cd my-landing npm run dev打开浏览器重点检查三件事主色是否等于#2563EB卡片圆角是否 12px按钮 hover 是否用了#1D4ED8。如果这三项都对说明 design.md 被正确读取了。你可以把 MODEL 换成gpt-5.4或gemini-3-pro再跑一次对比不同模型对同一份 design.md 的遵循程度这就是统一 Key 带来的多模型对比便利。5. 常见报错排查401、local proxy failed、reading choices接入过程中最容易卡在几个固定报错上这里逐个对照排查。401 Unauthorized先确认 Key 有没有复制完整前后有没有空格。再确认 Base URL 是不是https://taotoken.net/api不要多加/v1或斜杠。如果 Key 是在别的项目里用过、后来删了也会 401去控制台重新生成一个。local proxy failed这个通常出现在本地工具配置了代理但代理没启动或者 Base URL 写成了本地地址。检查你的环境变量里有没有残留的HTTP_PROXY、HTTPS_PROXY如果有就清掉。TaoToken 的地址是公网可直连的不需要额外代理配置。reading choices 报错一般是接口返回结构和你代码里取值的路径不一致。如果你用的是 OpenAI SDKresponse.choices[0].message.content是标准路径。如果报NoneType或list index out of range先打印完整 response 看看返回体确认模型 ID 是否拼写正确、是否被平台支持。OAuth 相关报错如果你在 Claude Code 或 Codex 里看到 OAuth 字样说明工具还在走它默认的登录流程没有读你的配置文件。检查配置文件路径是否正确环境变量是否被 shell 覆盖。必要时在启动命令前显式 export 一次。模型返回空内容把max_tokens调大或者把temperature降到 0.2。有些模型在长 design.md 输入下会先“思考”再输出如果 token 上限太小内容会被截断。排查顺序建议先确认 Key 和 Base URL再确认 Model ID最后看代码取值路径。三件套对了大部分报错都会消失。6. 把 AI 前端产出纳入工程化流程走到这里你已经有了 design.md 模板、agents.md 配置、统一 Key 接入方式和一段可运行的验证脚本。接下来要做的是把它变成团队日常流程的一部分。我的建议是把 design.md 和 agents.md 一起提交到项目仓库作为和 package.json 同级的工程文件。每次让 AI 生成或修改 UI 时系统提示词里固定写“遵循 design.md 和 agents.md”不要每次重新描述风格。多轮 refinement 时保留会话历史只追加“仍然遵循 design.md把 Hero 文案缩短”这类指令而不是重新塞一遍完整设计系统。如果你需要长期做编码和 Agent 协作可以了解 TaoToken 的 Coding Plan把多模型调用和额度管理统一起来如果只是偶尔验证模型效果用模型对话页面就够了接入文档里有各工具的详细配置说明遇到问题可以先查文档再排查。最后留一个实用技巧design.md 不要一次写太满先写色彩、字体、间距、按钮和卡片这五项跑通一轮生成再逐步补充动效和响应式规则。规则越少越确定模型遵循得越稳。等这套流程跑顺了你会发现 AI 生成的前端不再是“抽卡”而是可预期、可复现的工程产出。