1. 当设计系统遇上 AI Agent一个被低估的交叉地带先说一个我观察到的现象。过去两年团队里做设计系统的那拨人和做 AI Agent 的那拨人基本是两条平行线。设计系统的人天天在 Figma 里维护组件库、定 token、写使用规范做 Agent 的人天天在调 prompt、接工具、跑评测。两边开会都聊不到一块去。但最近半年这个边界开始模糊了。原因很直接当 Agent 开始真正参与产品界面相关的任务——比如根据需求生成页面、修改样式、调用组件、检查视觉一致性——它就必须读懂设计系统。而设计系统原本是给人看的不是给机器看的。这就是Design Systems for AI Agents这个方向的核心命题如何把一套原本服务于人类设计师和前端工程师的设计系统改造成 AI Agent 也能可靠消费、可靠执行的形式。我拿一个具体场景说明。假设你有一个 Agent任务是把登录页的主按钮改成品牌主色圆角改成 8px。对人类工程师来说这句话背后有一整套隐含知识主色是哪个 token、圆角在哪个变量里、改完要不要同步到暗色模式、组件库里的 Button 有几个 variant。这些知识散落在 Figma 文件、CSS 变量文件、组件文档、甚至某个老员工的脑子里。Agent 没有这些上下文它只能瞎猜猜错就是线上事故。所以这篇文章要解决的问题很明确怎么把设计系统里那些人默认知道的东西变成 Agent 能稳定读取和执行的结构化信息。涉及的关键词包括 AI Agents、Design Systems、AGENTS.md、CSS、Figma 这几个。适合三类人看正在维护设计系统的前端/设计工程师、正在做 Agent 工具链的开发者、以及想把两者接起来的技术负责人。不管你是刚接触这个概念还是已经在踩坑下面这些内容应该都能对上号。2. 为什么传统设计系统对 Agent 不友好2.1 设计系统的三层结构Agent 只吃得到最浅一层一套成熟的设计系统我习惯把它拆成三层Token 层颜色、间距、字号、圆角、阴影这些原子值。通常以 CSS 变量、JSON、或者 Figma Variables 的形式存在。组件层Button、Input、Card 这些封装好的组件带 props 和 variant。规范层什么时候用哪个组件、什么场景用什么颜色、间距的节奏规则。这一层基本是文档和口头约定。Agent 最容易吃到的是 Token 层因为它是结构化的。组件层次之如果组件库有 TypeScript 类型定义或者 StorybookAgent 还能解析。最难的是规范层——主按钮一屏只能有一个危险操作要用 destructive variant这类规则往往写在 Confluence 里或者压根没写。问题就在这Agent 做界面任务时出错最多的地方恰恰是规范层。它知道有红色但不知道红色什么时候该用它知道有 Button 组件但不知道哪个 variant 对应主操作。2.2 Figma 是给人看的不是给机器读的Figma 是设计系统的事实源头。但 Figma 文件的结构对 Agent 极不友好。图层命名混乱Frame 427这种、组件嵌套深、变体命名不统一、注释散落各处。我见过一个团队同一个按钮组件在 Figma 里有三种命名Button/Primary、btn-main、主要按钮。人靠视觉能认出来Agent 靠字符串匹配就崩了。Figma 的 Variables 功能是个进步它把 token 结构化了。但 Variables 和代码里的 CSS 变量之间往往没有强绑定改了一边忘了另一边这种漂移对 Agent 是致命的——它不知道该信哪个。2.3 缺失的机器可读契约说到底传统设计系统缺的是一份机器可读契约。这份契约要回答几个问题问题人类怎么获取Agent 怎么获取现状有哪些 token看文档/问人解析 CSS 变量文件token 的语义看命名和注释基本靠猜组件有哪些 variant看 Storybook解析类型定义什么时候用哪个看规范文档无改动的约束团队约定无这张表右边那一列就是我们要补的坑。而AGENTS.md这个约定正好是补坑的一个抓手。3. AGENTS.md给 Agent 的一份设计系统说明书3.1 AGENTS.md 到底是什么定位AGENTS.md是近一年在 Agent 工具链里逐渐形成的一个约定在项目根目录放一个 Markdown 文件告诉 Agent 这个项目的结构、约定、禁忌、常用命令。它本质上是给 Agent 看的 README。很多人第一次听到会问这不就是 README 吗区别在于README 是给人看的讲究叙事和引导AGENTS.md 是给机器看的讲究精确、无歧义、可执行。人能从模糊描述里推断意图Agent 不行。放到设计系统场景里AGENTS.md 要承担的角色是把设计系统里那些隐性的、散落的规则集中成一份 Agent 每次任务都会读的契约文件。3.2 一份面向设计系统的 AGENTS.md 该写什么我按实际项目经验给一个结构参考。注意这不是模板照抄而是说明每一块为什么存在。# AGENTS.md ## 设计系统概览 - Token 源文件src/styles/tokens.css唯一真源禁止在组件内硬编码颜色/间距 - 组件库src/components/ui/基于 React TypeScript - 设计源Figma 文件 DesignSystem-v3Variables 与 tokens.css 保持同步 ## Token 命名规则 - 颜色--color-{语义}-{强度}如 --color-primary-500 - 间距--space-{n}n 为 4 的倍数4/8/12/16... - 圆角--radius-{sm|md|lg|full} ## 组件使用约束 - 一屏内 primary 按钮不超过 1 个 - 危险操作必须用 variantdestructive - 表单错误提示统一用 Text varianterror ## 禁止事项 - 禁止在 JSX 内写死十六进制颜色 - 禁止新增未在 tokens.css 中定义的间距值 - 禁止直接修改 src/components/ui/ 下的文件改动需走组件库流程 ## 常用命令 - 校验 token 一致性npm run lint:tokens - 生成组件文档npm run docs:gen这份文件的价值在于Agent 每次动手前读一遍就能避开 80% 的低级错误。我实测下来加了这份文件之后Agent 生成代码里硬编码颜色的比例从大概三成降到了个位数。3.3 为什么用 Markdown 而不是 JSON Schema有人会问既然要机器读为什么不直接上 JSON Schema我的经验是AGENTS.md 的读者是 LLM不是传统解析器。LLM 对自然语言 结构化 Markdown 的理解能力远好于对严格 Schema 的解析。而且 Markdown 对人也可读维护成本低设计师也能看懂并参与修改。JSON Schema 适合做校验不适合做说明。理想组合是AGENTS.md 负责说明和约束配套一个 lint 脚本负责校验。两者分工各司其职。4. 把 Token 层做成 Agent 的可信数据源4.1 单一真源是底线Agent 出错的一大来源是信息冲突。CSS 变量文件里--color-primary是#3B82F6Figma Variables 里是#2563EB组件里又硬编码了一个#1D4ED8。人可能靠经验判断用哪个Agent 只会随机挑一个。所以第一步是确立单一真源。我的做法是以代码里的 tokens.css 为唯一真源Figma Variables 通过插件或脚本单向同步过去。方向很重要只能代码到 Figma不能反过来否则又会漂移。/* tokens.css —— 唯一真源 */ :root { /* 颜色语义化命名不暴露具体色值含义 */ --color-primary-500: #2563eb; --color-primary-600: #1d4ed8; --color-danger-500: #dc2626; --color-neutral-100: #f5f5f5; --color-neutral-900: #171717; /* 间距4 的倍数体系 */ --space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px; --space-6: 24px; /* 圆角 */ --radius-sm: 4px; --radius-md: 8px; --radius-lg: 16px; --radius-full: 9999px; }注意语义化命名是关键。--color-primary-500比--color-blue-500对 Agent 友好得多因为前者携带了这是主色的语义Agent 在需要主色时能直接匹配。4.2 给 Token 补上使用场景注释光有命名还不够。Agent 知道--color-danger-500是危险色但不知道什么时候用。所以在 tokens.css 里加注释把使用场景写清楚:root { /* 主色用于主操作按钮、链接、选中态。一屏内主色元素不超过 2 处 */ --color-primary-500: #2563eb; /* 危险色仅用于删除、不可逆操作、错误状态。禁止用于普通强调 */ --color-danger-500: #dc2626; }这些注释会被 Agent 读到成为它决策的依据。我试过对比不加注释时Agent 会把 danger 色用在重要提示上加了注释后它基本能正确区分危险和重要。4.3 用 lint 脚本守住底线光靠 Agent 自觉不够得有校验。写一个简单的 lint 脚本扫描代码里有没有硬编码的颜色和间距// scripts/lint-tokens.js const fs require(fs); const path require(path); const HEX_COLOR /#[0-9a-fA-F]{3,8}\b/g; const RAW_PX /\b\dpx\b/g; const ALLOWED_FILES [tokens.css]; function lintFile(filePath) { const content fs.readFileSync(filePath, utf-8); const issues []; if (!ALLOWED_FILES.some(f filePath.endsWith(f))) { const hexMatches content.match(HEX_COLOR); if (hexMatches) { issues.push(发现硬编码颜色: ${hexMatches.join(, )}); } } return issues; } // 遍历 src 目录输出问题这个脚本挂到 CI 上Agent 提交的代码如果硬编码了颜色直接打回。约束不是靠信任是靠机制。5. 组件层让 Agent 知道有哪些积木、怎么拼5.1 组件元数据要显式暴露Agent 用组件前提是它知道组件存在、知道 props、知道 variant。TypeScript 类型定义能解决一部分但类型定义里没有什么时候用的语义。我的做法是给每个核心组件配一份元数据可以放在组件同目录的meta.json也可以集中放一个文件{ name: Button, variants: { primary: 主操作一屏最多一个, secondary: 次要操作, destructive: 删除、不可逆操作, ghost: 低优先级操作如取消 }, props: { size: [sm, md, lg], disabled: 布尔值禁用态 }, constraints: [ 禁止在 primary 按钮上叠加 destructive 样式, loading 态必须配合 disabled 使用 ] }这份元数据配合 AGENTS.md 一起读Agent 就能在生成代码时做出合理选择。实测中Agent 从随便挑一个 variant变成了根据操作性质选 variant准确率提升明显。5.2 用 Storybook 做 Agent 的可视化参考Storybook 原本是给人看组件效果的但它对 Agent 也有价值每个 story 都是一份组件在特定 props 下的正确用法示例。Agent 可以读取 story 源码学习组件的标准用法。关键是 story 的命名要规范。Button.Primary、Button.Destructive这种命名Agent 能直接对应到 variant。如果命名是Story1、Story2那就白搭。5.3 组件文档里的反例比正例更有价值这点是我踩坑后才意识到的。正例告诉 Agent 怎么做反例告诉 Agent 不能怎么做。而 Agent 犯错往往是因为不知道边界在哪。所以在组件文档里我会专门写一段常见误用## Button 常见误用 - 误用用 primary 按钮做取消操作 正确取消用 ghost 或 secondary - 误用一个表单里放三个 primary 按钮 正确只保留提交按钮为 primary其余降级 - 误用用 danger 色做普通强调文字 正确danger 仅用于错误和危险操作这些反例被 Agent 读到后能显著减少看起来对但不符合规范的输出。6. Figma 与代码的桥接别让 Agent 在两套真源间迷路6.1 Figma Variables 与 CSS 变量的同步策略前面说了以代码为真源。但实际操作中设计师在 Figma 里改东西是常态怎么保证不漂移我的方案是用 Figma 插件把 Variables 导出成 JSON再用脚本对比代码里的 tokens.css有差异就报警。不是自动同步而是自动检测。因为自动同步有风险——设计师可能只是试验性地改了个值自动同步会把试验值推到线上。// scripts/check-token-drift.js const figmaTokens require(./figma-tokens-export.json); const cssTokens parseCssTokens(./src/styles/tokens.css); const drift []; for (const [key, value] of Object.entries(figmaTokens)) { if (cssTokens[key] cssTokens[key] ! value) { drift.push({ key, figma: value, css: cssTokens[key] }); } } if (drift.length 0) { console.error(Token 漂移检测到差异); console.table(drift); process.exit(1); }这个脚本挂到 CI 上每次 Figma 导出更新后跑一次有漂移就人工介入。Agent 最怕的就是两套真源打架这个脚本就是防打架的。6.2 图层命名规范Agent 靠它认组件Figma 图层命名对 Agent 的影响比大多数人想的大。如果 Agent 要通过 Figma 的 API 读取设计稿来生成代码图层名就是它的路标。我建议的命名规范组件实例直接用组件名如Button/Primary布局容器语义化如Header、Sidebar、MainContent禁止Frame 427、Group 12、Rectangle这类默认名这条规范对人也有好处但主要是为 Agent 铺路。我见过一个项目图层命名规范后Agent 从设计稿生成代码的准确率提升了一大截因为它能正确识别这是导航栏这是主内容区。6.3 别指望 Agent 直接读 Figma给它中间产物一个务实的建议不要让 Agent 直接对接 Figma API。Figma 的数据结构复杂Agent 解析起来容易出错而且 API 调用有频率限制。更好的做法是用脚本把 Figma 的关键信息组件列表、token、布局结构导出成一份简化的 JSON 或 MarkdownAgent 读这份中间产物。这样既稳定又快。7. 实操中踩过的坑和验证方法7.1 坑一AGENTS.md 写太长Agent 反而抓不住重点我一开始把 AGENTS.md 写得特别详细恨不得把整个设计系统文档搬进去。结果 Agent 的表现反而下降了——信息过载它抓不住关键约束。后来我改成分层AGENTS.md 只放最高频、最关键的约束控制在 100 行以内详细规范放到docs/design-system/下AGENTS.md 里用链接引用。Agent 需要细节时再去读。经验AGENTS.md 是必读摘要不是完整手册。宁可少而精不要多而杂。7.2 坑二约束写了但没校验Agent 照样违反光在 AGENTS.md 里写禁止硬编码颜色Agent 该违反还是违反。因为 LLM 不是确定性执行器它只是倾向于遵守。所以每条关键约束都要配一个校验机制。禁止硬编码颜色就上 lint禁止一屏多个 primary 按钮就写个静态检查禁止改组件库文件就用 git hook 拦截。约束 校验双保险。7.3 坑三Token 语义和 Agent 的理解对不上有次 Agent 把--color-neutral-900用在了正文文字上看起来没问题但规范里正文应该用--color-text-primary。原因是neutral-900这个名字对 Agent 来说是深灰色而text-primary才是正文色。语义层缺失Agent 只能按字面理解。解决办法是补一层语义 token:root { /* 原始色板 */ --color-neutral-900: #171717; /* 语义层Agent 优先用这一层 */ --color-text-primary: var(--color-neutral-900); --color-text-secondary: var(--color-neutral-600); --color-bg-surface: #ffffff; }AGENTS.md 里明确写优先使用语义 token原始色板仅在设计系统内部使用。这样 Agent 就不会乱抓了。7.4 怎么验证 Agent 真的读懂了设计系统验证方法我总结了三步单元测试式验证给 Agent 一批标准任务如生成一个带主按钮的表单检查输出是否符合规范。跑 20 个任务统计违规率。对抗式验证故意给模糊指令如把这个按钮改好看点看 Agent 会不会乱改 token。回归验证每次改 AGENTS.md 或 tokens.css 后重跑前两步确保没退化。我实测下来一套设计系统从Agent 完全读不懂到基本可靠大概需要两到三轮迭代。第一轮补 AGENTS.md第二轮补语义 token第三轮补校验脚本。每轮都能看到违规率明显下降。8. 一个可复现的最小落地路径如果你现在就想动手我给一条最小路径不需要大动干戈第一步在项目根目录建AGENTS.md先写三块内容token 源文件位置、组件库位置、三条最重要的禁止事项。控制在 50 行以内。第二步检查 tokens.css把颜色和间距的命名改成语义化给每个关键 token 加一行使用场景注释。第三步写一个最简单的 lint 脚本只查硬编码颜色这一项挂到 CI。第四步给最常用的 3 到 5 个组件写 meta.json标注 variant 和使用约束。第五步跑一批标准任务记录 Agent 的违规情况针对性补 AGENTS.md。这五步做完大概一两天的工作量但 Agent 在界面任务上的可靠性会有肉眼可见的提升。后面再逐步补 Figma 同步、组件文档反例、更多校验规则。我个人在实际操作中的体会是这件事的难点不在技术在于把团队里那些默认知道的隐性知识显性化。写 AGENTS.md 的过程其实是一次设计系统的自我梳理。很多规则平时没人说得清写下来才发现团队内部理解都不一致。Agent 只是把这些不一致暴露出来了而已。从这个角度看为 Agent 优化设计系统反过来也让人用得更顺。
1. 当设计系统遇上 AI Agent一个被低估的交叉地带先说一个我观察到的现象。过去两年团队里做设计系统的那拨人和做 AI Agent 的那拨人基本是两条平行线。设计系统的人天天在 Figma 里维护组件库、定 token、写使用规范做 Agent 的人天天在调 prompt、接工具、跑评测。两边开会都聊不到一块去。但最近半年这个边界开始模糊了。原因很直接当 Agent 开始真正参与产品界面相关的任务——比如根据需求生成页面、修改样式、调用组件、检查视觉一致性——它就必须读懂设计系统。而设计系统原本是给人看的不是给机器看的。这就是Design Systems for AI Agents这个方向的核心命题如何把一套原本服务于人类设计师和前端工程师的设计系统改造成 AI Agent 也能可靠消费、可靠执行的形式。我拿一个具体场景说明。假设你有一个 Agent任务是把登录页的主按钮改成品牌主色圆角改成 8px。对人类工程师来说这句话背后有一整套隐含知识主色是哪个 token、圆角在哪个变量里、改完要不要同步到暗色模式、组件库里的 Button 有几个 variant。这些知识散落在 Figma 文件、CSS 变量文件、组件文档、甚至某个老员工的脑子里。Agent 没有这些上下文它只能瞎猜猜错就是线上事故。所以这篇文章要解决的问题很明确怎么把设计系统里那些人默认知道的东西变成 Agent 能稳定读取和执行的结构化信息。涉及的关键词包括 AI Agents、Design Systems、AGENTS.md、CSS、Figma 这几个。适合三类人看正在维护设计系统的前端/设计工程师、正在做 Agent 工具链的开发者、以及想把两者接起来的技术负责人。不管你是刚接触这个概念还是已经在踩坑下面这些内容应该都能对上号。2. 为什么传统设计系统对 Agent 不友好2.1 设计系统的三层结构Agent 只吃得到最浅一层一套成熟的设计系统我习惯把它拆成三层Token 层颜色、间距、字号、圆角、阴影这些原子值。通常以 CSS 变量、JSON、或者 Figma Variables 的形式存在。组件层Button、Input、Card 这些封装好的组件带 props 和 variant。规范层什么时候用哪个组件、什么场景用什么颜色、间距的节奏规则。这一层基本是文档和口头约定。Agent 最容易吃到的是 Token 层因为它是结构化的。组件层次之如果组件库有 TypeScript 类型定义或者 StorybookAgent 还能解析。最难的是规范层——主按钮一屏只能有一个危险操作要用 destructive variant这类规则往往写在 Confluence 里或者压根没写。问题就在这Agent 做界面任务时出错最多的地方恰恰是规范层。它知道有红色但不知道红色什么时候该用它知道有 Button 组件但不知道哪个 variant 对应主操作。2.2 Figma 是给人看的不是给机器读的Figma 是设计系统的事实源头。但 Figma 文件的结构对 Agent 极不友好。图层命名混乱Frame 427这种、组件嵌套深、变体命名不统一、注释散落各处。我见过一个团队同一个按钮组件在 Figma 里有三种命名Button/Primary、btn-main、主要按钮。人靠视觉能认出来Agent 靠字符串匹配就崩了。Figma 的 Variables 功能是个进步它把 token 结构化了。但 Variables 和代码里的 CSS 变量之间往往没有强绑定改了一边忘了另一边这种漂移对 Agent 是致命的——它不知道该信哪个。2.3 缺失的机器可读契约说到底传统设计系统缺的是一份机器可读契约。这份契约要回答几个问题问题人类怎么获取Agent 怎么获取现状有哪些 token看文档/问人解析 CSS 变量文件token 的语义看命名和注释基本靠猜组件有哪些 variant看 Storybook解析类型定义什么时候用哪个看规范文档无改动的约束团队约定无这张表右边那一列就是我们要补的坑。而AGENTS.md这个约定正好是补坑的一个抓手。3. AGENTS.md给 Agent 的一份设计系统说明书3.1 AGENTS.md 到底是什么定位AGENTS.md是近一年在 Agent 工具链里逐渐形成的一个约定在项目根目录放一个 Markdown 文件告诉 Agent 这个项目的结构、约定、禁忌、常用命令。它本质上是给 Agent 看的 README。很多人第一次听到会问这不就是 README 吗区别在于README 是给人看的讲究叙事和引导AGENTS.md 是给机器看的讲究精确、无歧义、可执行。人能从模糊描述里推断意图Agent 不行。放到设计系统场景里AGENTS.md 要承担的角色是把设计系统里那些隐性的、散落的规则集中成一份 Agent 每次任务都会读的契约文件。3.2 一份面向设计系统的 AGENTS.md 该写什么我按实际项目经验给一个结构参考。注意这不是模板照抄而是说明每一块为什么存在。# AGENTS.md ## 设计系统概览 - Token 源文件src/styles/tokens.css唯一真源禁止在组件内硬编码颜色/间距 - 组件库src/components/ui/基于 React TypeScript - 设计源Figma 文件 DesignSystem-v3Variables 与 tokens.css 保持同步 ## Token 命名规则 - 颜色--color-{语义}-{强度}如 --color-primary-500 - 间距--space-{n}n 为 4 的倍数4/8/12/16... - 圆角--radius-{sm|md|lg|full} ## 组件使用约束 - 一屏内 primary 按钮不超过 1 个 - 危险操作必须用 variantdestructive - 表单错误提示统一用 Text varianterror ## 禁止事项 - 禁止在 JSX 内写死十六进制颜色 - 禁止新增未在 tokens.css 中定义的间距值 - 禁止直接修改 src/components/ui/ 下的文件改动需走组件库流程 ## 常用命令 - 校验 token 一致性npm run lint:tokens - 生成组件文档npm run docs:gen这份文件的价值在于Agent 每次动手前读一遍就能避开 80% 的低级错误。我实测下来加了这份文件之后Agent 生成代码里硬编码颜色的比例从大概三成降到了个位数。3.3 为什么用 Markdown 而不是 JSON Schema有人会问既然要机器读为什么不直接上 JSON Schema我的经验是AGENTS.md 的读者是 LLM不是传统解析器。LLM 对自然语言 结构化 Markdown 的理解能力远好于对严格 Schema 的解析。而且 Markdown 对人也可读维护成本低设计师也能看懂并参与修改。JSON Schema 适合做校验不适合做说明。理想组合是AGENTS.md 负责说明和约束配套一个 lint 脚本负责校验。两者分工各司其职。4. 把 Token 层做成 Agent 的可信数据源4.1 单一真源是底线Agent 出错的一大来源是信息冲突。CSS 变量文件里--color-primary是#3B82F6Figma Variables 里是#2563EB组件里又硬编码了一个#1D4ED8。人可能靠经验判断用哪个Agent 只会随机挑一个。所以第一步是确立单一真源。我的做法是以代码里的 tokens.css 为唯一真源Figma Variables 通过插件或脚本单向同步过去。方向很重要只能代码到 Figma不能反过来否则又会漂移。/* tokens.css —— 唯一真源 */ :root { /* 颜色语义化命名不暴露具体色值含义 */ --color-primary-500: #2563eb; --color-primary-600: #1d4ed8; --color-danger-500: #dc2626; --color-neutral-100: #f5f5f5; --color-neutral-900: #171717; /* 间距4 的倍数体系 */ --space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px; --space-6: 24px; /* 圆角 */ --radius-sm: 4px; --radius-md: 8px; --radius-lg: 16px; --radius-full: 9999px; }注意语义化命名是关键。--color-primary-500比--color-blue-500对 Agent 友好得多因为前者携带了这是主色的语义Agent 在需要主色时能直接匹配。4.2 给 Token 补上使用场景注释光有命名还不够。Agent 知道--color-danger-500是危险色但不知道什么时候用。所以在 tokens.css 里加注释把使用场景写清楚:root { /* 主色用于主操作按钮、链接、选中态。一屏内主色元素不超过 2 处 */ --color-primary-500: #2563eb; /* 危险色仅用于删除、不可逆操作、错误状态。禁止用于普通强调 */ --color-danger-500: #dc2626; }这些注释会被 Agent 读到成为它决策的依据。我试过对比不加注释时Agent 会把 danger 色用在重要提示上加了注释后它基本能正确区分危险和重要。4.3 用 lint 脚本守住底线光靠 Agent 自觉不够得有校验。写一个简单的 lint 脚本扫描代码里有没有硬编码的颜色和间距// scripts/lint-tokens.js const fs require(fs); const path require(path); const HEX_COLOR /#[0-9a-fA-F]{3,8}\b/g; const RAW_PX /\b\dpx\b/g; const ALLOWED_FILES [tokens.css]; function lintFile(filePath) { const content fs.readFileSync(filePath, utf-8); const issues []; if (!ALLOWED_FILES.some(f filePath.endsWith(f))) { const hexMatches content.match(HEX_COLOR); if (hexMatches) { issues.push(发现硬编码颜色: ${hexMatches.join(, )}); } } return issues; } // 遍历 src 目录输出问题这个脚本挂到 CI 上Agent 提交的代码如果硬编码了颜色直接打回。约束不是靠信任是靠机制。5. 组件层让 Agent 知道有哪些积木、怎么拼5.1 组件元数据要显式暴露Agent 用组件前提是它知道组件存在、知道 props、知道 variant。TypeScript 类型定义能解决一部分但类型定义里没有什么时候用的语义。我的做法是给每个核心组件配一份元数据可以放在组件同目录的meta.json也可以集中放一个文件{ name: Button, variants: { primary: 主操作一屏最多一个, secondary: 次要操作, destructive: 删除、不可逆操作, ghost: 低优先级操作如取消 }, props: { size: [sm, md, lg], disabled: 布尔值禁用态 }, constraints: [ 禁止在 primary 按钮上叠加 destructive 样式, loading 态必须配合 disabled 使用 ] }这份元数据配合 AGENTS.md 一起读Agent 就能在生成代码时做出合理选择。实测中Agent 从随便挑一个 variant变成了根据操作性质选 variant准确率提升明显。5.2 用 Storybook 做 Agent 的可视化参考Storybook 原本是给人看组件效果的但它对 Agent 也有价值每个 story 都是一份组件在特定 props 下的正确用法示例。Agent 可以读取 story 源码学习组件的标准用法。关键是 story 的命名要规范。Button.Primary、Button.Destructive这种命名Agent 能直接对应到 variant。如果命名是Story1、Story2那就白搭。5.3 组件文档里的反例比正例更有价值这点是我踩坑后才意识到的。正例告诉 Agent 怎么做反例告诉 Agent 不能怎么做。而 Agent 犯错往往是因为不知道边界在哪。所以在组件文档里我会专门写一段常见误用## Button 常见误用 - 误用用 primary 按钮做取消操作 正确取消用 ghost 或 secondary - 误用一个表单里放三个 primary 按钮 正确只保留提交按钮为 primary其余降级 - 误用用 danger 色做普通强调文字 正确danger 仅用于错误和危险操作这些反例被 Agent 读到后能显著减少看起来对但不符合规范的输出。6. Figma 与代码的桥接别让 Agent 在两套真源间迷路6.1 Figma Variables 与 CSS 变量的同步策略前面说了以代码为真源。但实际操作中设计师在 Figma 里改东西是常态怎么保证不漂移我的方案是用 Figma 插件把 Variables 导出成 JSON再用脚本对比代码里的 tokens.css有差异就报警。不是自动同步而是自动检测。因为自动同步有风险——设计师可能只是试验性地改了个值自动同步会把试验值推到线上。// scripts/check-token-drift.js const figmaTokens require(./figma-tokens-export.json); const cssTokens parseCssTokens(./src/styles/tokens.css); const drift []; for (const [key, value] of Object.entries(figmaTokens)) { if (cssTokens[key] cssTokens[key] ! value) { drift.push({ key, figma: value, css: cssTokens[key] }); } } if (drift.length 0) { console.error(Token 漂移检测到差异); console.table(drift); process.exit(1); }这个脚本挂到 CI 上每次 Figma 导出更新后跑一次有漂移就人工介入。Agent 最怕的就是两套真源打架这个脚本就是防打架的。6.2 图层命名规范Agent 靠它认组件Figma 图层命名对 Agent 的影响比大多数人想的大。如果 Agent 要通过 Figma 的 API 读取设计稿来生成代码图层名就是它的路标。我建议的命名规范组件实例直接用组件名如Button/Primary布局容器语义化如Header、Sidebar、MainContent禁止Frame 427、Group 12、Rectangle这类默认名这条规范对人也有好处但主要是为 Agent 铺路。我见过一个项目图层命名规范后Agent 从设计稿生成代码的准确率提升了一大截因为它能正确识别这是导航栏这是主内容区。6.3 别指望 Agent 直接读 Figma给它中间产物一个务实的建议不要让 Agent 直接对接 Figma API。Figma 的数据结构复杂Agent 解析起来容易出错而且 API 调用有频率限制。更好的做法是用脚本把 Figma 的关键信息组件列表、token、布局结构导出成一份简化的 JSON 或 MarkdownAgent 读这份中间产物。这样既稳定又快。7. 实操中踩过的坑和验证方法7.1 坑一AGENTS.md 写太长Agent 反而抓不住重点我一开始把 AGENTS.md 写得特别详细恨不得把整个设计系统文档搬进去。结果 Agent 的表现反而下降了——信息过载它抓不住关键约束。后来我改成分层AGENTS.md 只放最高频、最关键的约束控制在 100 行以内详细规范放到docs/design-system/下AGENTS.md 里用链接引用。Agent 需要细节时再去读。经验AGENTS.md 是必读摘要不是完整手册。宁可少而精不要多而杂。7.2 坑二约束写了但没校验Agent 照样违反光在 AGENTS.md 里写禁止硬编码颜色Agent 该违反还是违反。因为 LLM 不是确定性执行器它只是倾向于遵守。所以每条关键约束都要配一个校验机制。禁止硬编码颜色就上 lint禁止一屏多个 primary 按钮就写个静态检查禁止改组件库文件就用 git hook 拦截。约束 校验双保险。7.3 坑三Token 语义和 Agent 的理解对不上有次 Agent 把--color-neutral-900用在了正文文字上看起来没问题但规范里正文应该用--color-text-primary。原因是neutral-900这个名字对 Agent 来说是深灰色而text-primary才是正文色。语义层缺失Agent 只能按字面理解。解决办法是补一层语义 token:root { /* 原始色板 */ --color-neutral-900: #171717; /* 语义层Agent 优先用这一层 */ --color-text-primary: var(--color-neutral-900); --color-text-secondary: var(--color-neutral-600); --color-bg-surface: #ffffff; }AGENTS.md 里明确写优先使用语义 token原始色板仅在设计系统内部使用。这样 Agent 就不会乱抓了。7.4 怎么验证 Agent 真的读懂了设计系统验证方法我总结了三步单元测试式验证给 Agent 一批标准任务如生成一个带主按钮的表单检查输出是否符合规范。跑 20 个任务统计违规率。对抗式验证故意给模糊指令如把这个按钮改好看点看 Agent 会不会乱改 token。回归验证每次改 AGENTS.md 或 tokens.css 后重跑前两步确保没退化。我实测下来一套设计系统从Agent 完全读不懂到基本可靠大概需要两到三轮迭代。第一轮补 AGENTS.md第二轮补语义 token第三轮补校验脚本。每轮都能看到违规率明显下降。8. 一个可复现的最小落地路径如果你现在就想动手我给一条最小路径不需要大动干戈第一步在项目根目录建AGENTS.md先写三块内容token 源文件位置、组件库位置、三条最重要的禁止事项。控制在 50 行以内。第二步检查 tokens.css把颜色和间距的命名改成语义化给每个关键 token 加一行使用场景注释。第三步写一个最简单的 lint 脚本只查硬编码颜色这一项挂到 CI。第四步给最常用的 3 到 5 个组件写 meta.json标注 variant 和使用约束。第五步跑一批标准任务记录 Agent 的违规情况针对性补 AGENTS.md。这五步做完大概一两天的工作量但 Agent 在界面任务上的可靠性会有肉眼可见的提升。后面再逐步补 Figma 同步、组件文档反例、更多校验规则。我个人在实际操作中的体会是这件事的难点不在技术在于把团队里那些默认知道的隐性知识显性化。写 AGENTS.md 的过程其实是一次设计系统的自我梳理。很多规则平时没人说得清写下来才发现团队内部理解都不一致。Agent 只是把这些不一致暴露出来了而已。从这个角度看为 Agent 优化设计系统反过来也让人用得更顺。
知识建站
内容驱动
阅读友好版式
SEO 精细化
线索转化