1. 前端 AI 生成 UI 总在“能跑但丑”上翻车DESIGN.md skill 到底解决什么问题AI 编程助手写前端最让人抓狂的不是逻辑跑不通而是页面能打开、按钮能点但整体透着一股“实习生赶工”的味道。同一个提示词今天生成的是圆角 8px 的卡片明天变成 2px 直角今天主色是 #3B82F6明天变成 #2563EB间距一会儿 12px 一会儿 20px。你反复在对话里补“用蓝色”“圆角大一点”“间距统一”它每次都答应下次生成又漂移。这个问题的根子在于AI 编程助手默认没有“视觉协议”。它每次生成 UI 都是即兴发挥没有一份稳定的约束文件告诉它“这个项目用什么色板、什么圆角、什么间距节奏、什么组件风格”。你靠对话临时补规则规则散落在几十轮上下文里模型记不住也执行不稳。DESIGN.md skill 的思路很直接把视觉规范写成一份 Markdown 文件放在项目根目录作为 AI 编程助手每次生成 UI 时必须读取的“设计契约”。这份文件里写清楚配色 token、间距刻度、圆角规则、字体层级、组件风格倾向甚至可以指定“照着某个大厂的设计语言来”。AI 编程助手在写组件前先读这份文件生成结果就有了统一的审美基准。适合谁用三类人最受益。第一类是独立开发者或小团队没有专职设计师但希望 AI 生成的界面看起来“像正经产品”。第二类是前端工程师用 Cursor、Claude Code、Codex 这类工具做页面重构或新功能开发受够了每次手动调 CSS 细节。第三类是技术负责人想把团队的视觉规范沉淀成一份 AI 可读的文件让不同人用 AI 生成 UI 时输出一致。我试过在同一个项目里不加 DESIGN.md 直接让 AI 写一个定价卡片组件生成结果用了三种不同的阴影、两种圆角、主色偏紫加上 DESIGN.md 约束后同一个提示词生成的卡片色板、圆角、间距、阴影层级全部对齐基本不用手改。差别就是这么明显。这篇会给出 DESIGN.md 的骨架示例、在 AI 编程工具里的挂载配置、用同一提示词对比验证审美一致性的具体动作以及常见报错排查。全程可跟做不需要设计背景。2. TaoToken 前置把模型接入和 Key 管理理顺DESIGN.md skill 才能稳定跑起来DESIGN.md skill 本身是一份文件加一套调用约定但它要发挥作用前提是你的 AI 编程助手能稳定调用模型。如果你用的是 Claude Code、Cursor、Cline 这类工具模型接入的 Base URL、API Key、Model ID 三件套必须先配对否则 skill 挂载了也跑不起来。TaoToken 在这里的角色是提供统一的模型接入入口。你可以在官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 了解整体能力API 入口是 https://taotoken.net/api这个地址不加 UTM。它的控制台、API Keys 管理、模型对话、Coding Plan 几个入口分别对应不同使用场景。先说清楚三件套怎么配。不管你用哪个 AI 编程工具接入任何模型服务都需要三个参数参数作用从哪里拿Base URL模型服务的请求地址TaoToken API 入口通常填 https://taotoken.net/apiAPI Key身份凭证TaoToken 控制台的 API Keys 页面生成Model ID指定调用哪个模型控制台或文档里列出的模型标识这三个参数缺一个请求就会失败。最常见的报错是 401意思是 Key 无效或没带还有 local proxy failed通常是 Base URL 填错或网络层配置有问题reading choices 报错一般是返回体格式和工具预期不匹配多半是 Model ID 写错或该模型不支持当前调用方式。具体操作路径先到控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建项目或直接进 API Keys 页面生成一个 Key 并复制保存。然后到接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 确认当前支持的模型列表和对应的 Model ID 写法。如果你只是想在对话里验证模型能不能用可以直接用模型对话入口 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 发一条测试消息。对于长期做前端编码和 Agent 任务的场景Coding Plan 更合适入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。它针对编码类调用做了额度规划比按次调用更省心。如果你用的是 Claude Code接入配置通常在 settings 文件里写 Base URL 和 Key如果用 Cline 或 Roo Code配置在 MCP 或 provider 设置里如果用 Codex配置在 auth.json 里。不管哪个工具三件套的填写逻辑一致Base URL 指向 TaoToken API 入口Key 用控制台生成的Model ID 按文档写。这里有个容易踩的坑有人把 Base URL 填成官网首页地址结果请求打到网页上返回 HTML 而不是 JSON工具就报 reading choices 或解析失败。记住 API 入口是 https://taotoken.net/api不带 UTM 参数不要和官网首页混用。Key 管理上建议一个项目一个 Key方便排查和回收。控制台里可以给 Key 加备注比如“前端项目-DESIGN.md 测试”这样出问题时能快速定位是哪个 Key 的调用异常。Key 不要写进前端代码或提交到 Git放在本地环境变量或工具的配置文件里。模型接入理顺之后DESIGN.md skill 的挂载才有意义。因为 skill 的本质是“在每次生成 UI 前让模型先读一份约束文件”这个读取动作依赖模型调用链路稳定。如果模型调用本身时好时坏skill 的效果就无从验证。3. 可复制配置DESIGN.md 骨架 AI 编程工具挂载片段这一节给两份可直接复制的东西一份 DESIGN.md 骨架一份在 AI 编程工具里的挂载配置。先看 DESIGN.md 骨架。这份骨架覆盖配色、间距、圆角、字体、阴影、组件风格六个维度。你可以直接复制到项目根目录按自己项目改数值。# DESIGN.md — 项目视觉规范 ## 1. 配色 Token | Token 名 | 值 | 用途 | |----------|-----|------| | --color-primary | #2563EB | 主按钮、链接、强调 | | --color-primary-hover | #1D4ED8 | 主按钮悬停 | | --color-bg | #FFFFFF | 页面背景 | | --color-bg-subtle | #F9FAFB | 卡片背景、分区背景 | | --color-text | #111827 | 主文本 | | --color-text-muted | #6B7280 | 次要文本、说明 | | --color-border | #E5E7EB | 分割线、卡片边框 | | --color-danger | #DC2626 | 错误、删除 | | --color-success | #16A34A | 成功、完成 | 规则禁止使用上表以外的颜色。禁止使用渐变作为大面积背景。主色只用于交互元素不用于装饰。 ## 2. 间距刻度 基础单位 4px只用以下刻度 - 4px图标与文字间距 - 8px紧凑元素间距 - 12px表单控件内间距 - 16px卡片内间距、段落间距 - 24px卡片之间、区块内分组 - 32px区块之间 - 48px页面大分区 - 64px页面顶部/底部留白 规则禁止出现 5px、10px、15px、20px 这类非刻度值。所有 margin/padding 必须从上述刻度取值。 ## 3. 圆角 | Token | 值 | 用途 | |-------|-----|------| | --radius-sm | 4px | 标签、小按钮 | | --radius-md | 8px | 按钮、输入框、卡片 | | --radius-lg | 12px | 模态框、大卡片 | | --radius-full | 9999px | 头像、胶囊标签 | 规则同一页面圆角层级不超过两种。卡片和按钮默认用 --radius-md。 ## 4. 字体层级 | 层级 | 字号 | 字重 | 行高 | 用途 | |------|------|------|------|------| | Display | 36px | 700 | 1.2 | 首屏大标题 | | H1 | 28px | 700 | 1.3 | 页面标题 | | H2 | 22px | 600 | 1.4 | 区块标题 | | H3 | 18px | 600 | 1.4 | 卡片标题 | | Body | 15px | 400 | 1.6 | 正文 | | Caption | 13px | 400 | 1.5 | 辅助说明 | 规则正文行高不低于 1.5。标题与正文之间至少留 8px 间距。 ## 5. 阴影 | Token | 值 | 用途 | |-------|-----|------| | --shadow-sm | 0 1px 2px rgba(0,0,0,0.05) | 卡片默认 | | --shadow-md | 0 4px 6px rgba(0,0,0,0.07) | 悬停、下拉 | | --shadow-lg | 0 10px 15px rgba(0,0,0,0.1) | 模态框 | 规则同一页面阴影层级不超过两种。禁止使用彩色阴影。 ## 6. 组件风格 - 按钮主按钮实心主色次按钮描边文字按钮无背景。高度 36px默认或 32px紧凑。 - 输入框1px 边框聚焦时边框变主色不加外发光。 - 卡片白底1px 边框--radius-md--shadow-sm内间距 16px 或 24px。 - 表格表头背景 --color-bg-subtle行高 44px分割线用 --color-border。 - 图标线性图标线宽 1.5px尺寸 16px 或 20px颜色跟随文本。 ## 7. 禁止事项 - 禁止使用规范外的颜色、间距、圆角值。 - 禁止使用大面积渐变、玻璃拟态、霓虹发光。 - 禁止在同一组件内混用多种圆角或阴影。 - 禁止使用 emoji 作为功能图标。这份骨架的关键是“可执行”。每一条规则都写成 AI 能直接判断的形式比如“禁止出现 5px、10px、15px、20px 这类非刻度值”而不是“间距要协调”。AI 对具体数值的遵守度远高于模糊描述。接下来是挂载配置。不同工具的挂载方式不同但核心逻辑一致让 AI 在生成 UI 前读取 DESIGN.md。如果你用 Claude Code可以在项目根目录的 CLAUDE.md 里加一段引用## 视觉规范 生成任何 UI 组件、页面、样式前必须先读取根目录 DESIGN.md并严格遵守其中的配色、间距、圆角、字体、阴影、组件风格规则。如果 DESIGN.md 中未定义的视觉属性选择最接近的已定义 token不要自创数值。如果你用 Cursor在.cursorrules或项目 rules 里加同样的引用。Cursor 的 rules 文件支持 Markdown直接写# 项目规则 ## UI 生成约束 所有前端 UI 代码生成必须遵守 DESIGN.md。读取路径项目根目录 /DESIGN.md。优先级DESIGN.md 用户临时指令 模型默认审美。如果你用 Cline 或 Roo Code在 MCP 配置或 custom instructions 里加{ customInstructions: 生成 UI 前先读取项目根目录 DESIGN.md严格遵守其中的视觉 token。禁止使用规范外的颜色、间距、圆角值。 }如果你用 Codex在 auth.json 同级目录放 DESIGN.md并在项目配置里引用。Codex 的配置通常涉及 Base URL、Key、Model ID 三件套加上 DESIGN.md 路径{ base_url: https://taotoken.net/api, api_key: 你的Key, model: 你的ModelID, project_rules: 生成 UI 前读取 DESIGN.md遵守视觉规范 }注意上面的 api_key 不要直接提交到仓库用环境变量或本地配置文件。Base URL 填 https://taotoken.net/apiModel ID 按接入文档写。挂载完成后你可以用一句话验证是否生效在对话框里输入“读取 DESIGN.md告诉我主色和圆角规则”。如果 AI 能准确说出 #2563EB 和 8px说明挂载成功。4. 验证请求与成功结果同一提示词对比生成确认审美一致性配置写完不算完得验证 DESIGN.md 真的在约束 AI 的输出。最直接的方法是用同一个提示词分别在“无 DESIGN.md”和“有 DESIGN.md”两种状态下生成同一个组件对比结果。先准备一个测试提示词比如生成一个定价卡片组件包含套餐名、价格、功能列表、CTA 按钮。用 React Tailwind CSS。第一轮临时把 DESIGN.md 移出项目根目录或者在新会话里不引用它让 AI 自由生成。记录生成结果的关键视觉属性主色值、圆角值、间距值、阴影值、字体层级。第二轮恢复 DESIGN.md在同一个工具里重新发同一个提示词。再记录一遍关键视觉属性。对比时重点看五个维度维度无 DESIGN.md 表现有 DESIGN.md 表现主色可能用 #3B82F6 或紫色固定 #2563EB圆角卡片 12px、按钮 6px 混用统一 8px间距出现 10px、20px 等非刻度值只用 4/8/12/16/24/32阴影可能用彩色阴影或大模糊只用 --shadow-sm字体标题字重不固定H3 固定 18px/600如果第二轮生成结果在这些维度上明显收敛说明 DESIGN.md 生效了。如果还是漂移检查挂载配置是否被工具正确读取或者 DESIGN.md 里的规则是否写得够具体。再做一个更严格的验证让 AI 连续生成三个不同组件按钮、卡片、表格检查它们之间的视觉一致性。没有 DESIGN.md 时三个组件的圆角和间距往往各不相同有 DESIGN.md 时三个组件应该共享同一套 token。还可以做“局部微调”验证。比如把 DESIGN.md 里的 --radius-md 从 8px 改成 12px然后重新生成同一个卡片组件。如果 AI 输出的圆角跟着变成 12px说明它确实在读取文件而不是凭记忆生成。验证过程中你可以用模型对话入口 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 单独发一条消息让模型复述 DESIGN.md 里的规则确认模型侧能正确解析这份文件。这一步能排除“工具没把文件传给模型”的问题。成功的结果长这样同一个提示词两次生成第二次的代码里颜色值、圆角值、间距值全部来自 DESIGN.md 定义的 token没有自创数值。你打开页面看卡片、按钮、文字层级协调不再有“拼凑感”。如果生成结果里出现了规范外的值比如 padding: 20px可以在对话里直接指出“DESIGN.md 规定间距只用 4/8/12/16/24/3220px 不在刻度内请改用 16px 或 24px。”模型通常会修正。这个反馈过程本身也能帮你发现 DESIGN.md 里哪些规则写得不够明确。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth 对照解决配置和验证过程中最容易卡在模型接入层。下面按真实报错逐条排查。401 Unauthorized这是最常见的。原因通常是 API Key 没填、填错、或者 Key 被删除/过期。排查步骤到控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 确认 Key 存在且状态正常检查工具配置里 Key 有没有多余空格或换行确认请求头里带了 Authorization: Bearer 你的Key。如果用的是 Claude Code检查 settings 里的 apiKey 字段如果用 Cline检查 provider 设置里的 API Key。local proxy failed这个报错通常和 Base URL 有关。常见原因是 Base URL 填成了官网首页而不是 API 入口或者填了带路径的地址导致请求打到错误端点。正确写法是 https://taotoken.net/api。另外检查本地网络层有没有额外配置干扰请求比如工具自带的代理设置。如果工具里有“使用系统代理”选项先关掉试试。reading choices 报错 / 解析失败这个报错说明请求发出去了但返回体格式和工具预期不匹配。最常见原因是 Model ID 写错或者该模型不支持当前调用方式比如用 chat 接口调了一个只支持 completion 的模型。排查到接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 核对 Model ID 的准确写法确认工具用的是 chat completions 还是 responses 接口如果工具支持自定义返回解析检查是否把 JSON 当成了流式处理。OAuth 相关报错有些工具比如 Claude Code 的某些版本默认走 OAuth 登录而不是 API Key。如果你要用 TaoToken 的 Key 接入需要在工具设置里切换到 API Key 模式关掉 OAuth 登录。具体路径Claude Code 在 settings 里把 auth 方式改成 apiKeyCursor 在模型设置里选“自定义 API Key”而不是“登录账号”。切换后重新填 Base URL、Key、Model ID 三件套。DESIGN.md 不生效如果模型接入正常但生成 UI 还是漂移排查三点第一DESIGN.md 是否在项目根目录文件名大小写是否一致第二工具的 rules 或 custom instructions 是否真的引用了 DESIGN.md有些工具需要重启或重新加载项目才生效第三DESIGN.md 里的规则是否够具体模糊描述如“间距要舒服”AI 无法执行必须写成具体数值。生成结果部分遵守、部分漂移这种情况通常是 DESIGN.md 太长或规则之间有冲突。比如配色表里定义了 --color-primary但组件风格里又写“按钮用蓝色”AI 可能困惑。解决确保 DESIGN.md 内部规则一致颜色统一用 token 名引用不写具体色值。另外如果 DESIGN.md 超过 200 行考虑拆成 DESIGN.md COMPONENTS.md主文件放 token组件文件放具体组件规则。Key 额度或限流问题如果请求偶尔成功偶尔失败可能是额度或限流。到控制台查看用量确认是否触发了速率限制。长期编码场景建议用 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 额度规划更适合高频调用。排查顺序建议先确认三件套Base URL、Key、Model ID正确再确认工具能正常调用模型最后确认 DESIGN.md 被正确读取。三层都通了审美一致性才有保障。6. 把视觉规范沉淀成 AI 可读文件长期编码用 Coding Plan 更稳DESIGN.md skill 的价值不在于“让 AI 一次生成好看的页面”而在于把视觉规范从“人脑记忆”变成“文件契约”。你不再需要每次在对话里重复“用蓝色”“圆角 8px”“间距 16px”而是把这些写进一份文件让 AI 每次生成前先读。这份文件可以进版本控制可以团队共享可以随项目演进迭代。实际操作上建议把 DESIGN.md 放在项目根目录和 README.md 同级。团队协作时谁改了视觉规范就改 DESIGN.mdAI 生成结果自动跟着变。新成员加入时不需要口头传达设计规则直接让他用 AI 生成一个组件看输出是否符合 DESIGN.md 即可。如果你做的是长期前端项目模型调用频率高Coding Plan 比按次调用更合适。入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。它针对编码场景做了额度规划适合每天都要用 AI 写组件的团队。最后给一个实用技巧DESIGN.md 不要一次写太满。先写配色、间距、圆角三个最影响观感的维度跑一周看 AI 在哪些地方还漂移再补规则。规则是迭代出来的不是一次设计出来的。你可以在项目里建一个 DESIGN-CHANGELOG.md记录每次调整的原因比如“2024-06-01 把卡片圆角从 8px 改成 12px因为用户反馈太硬”。这样规范演进有据可查AI 读取的始终是最新版本。模型接入方面Base URL 固定用 https://taotoken.net/apiKey 在控制台管理Model ID 按文档写。三件套配对DESIGN.md 挂载同一提示词对比验证审美一致性就能落地。