1. 前端设计质量审查为什么总在「人肉对齐」阶段卡住前端设计质量审查这件事做过的人都懂那种痛。设计稿在 Figma 里漂漂亮亮开发实现出来却总差那么点意思间距多了 2px、圆角从 8 变成了 6、主色用了#3B82F6而不是设计系统里的#2563EB。更麻烦的是这些问题往往要等到 UI 走查会上才被发现改一轮、测一轮时间全耗在来回对齐上。我见过不少团队的做法是拉一个「设计走查清单」的 Excel每次发版前人工逐条核对。清单本身没问题问题是它靠人记、靠人查一旦项目节奏快起来第一个被牺牲的就是它。Design Review 这个插件想解决的正是这个环节——把设计质量审查从「靠人盯」变成「有技能可调用、有画布可查看、有规则可复用」的工作流。它本质上是一个前端设计质量审查插件核心由两块组成Skills技能和Canvas画布查看器。Skills 负责「查什么、怎么查」Canvas 负责「把设计契约渲染成人能看懂的样子」。两者配合就能把一次设计审查从触发到输出问题清单跑通。适合谁用三类人最直接受益一是前端团队里负责 UI 还原度的同学二是需要维护设计系统的设计工程师三是想把设计审查纳入 CI 流程的技术负责人。如果你所在的项目有明确的 DESIGN.md 或设计 token 体系这个插件的价值会立刻放大。需要先说明一点这个插件本身不包含 MCP 服务器也没有独立 Agent 和命令文件所有能力都通过 Skill 调用触发。这意味着它的接入方式和你熟悉的那些「装完就有一堆斜杠命令」的插件不太一样得先理解 Skills 的编排逻辑才能真正用起来。下面我会把功能拆开讲再给一份可复制的配置清单和审查规则模板最后演示一次完整的验证动作。2. Skills 与 Canvas 的分工8 个技能到底各管什么要落地这套工作流先得把 Skills 的层级关系理清楚。Design Review 的 8 个技能不是平铺的而是分成了编排层和场景层两层。编排层只有一个技能design-qa它的作用是串联所有子技能完成端到端的设计审查场景层则是 7 个具体技能各自负责一个审查维度。先看编排层。design-qa是「全量设计 QA 编排器」你可以把它理解成审查流程的总调度。当你需要一次完整的设计质量审查时调用它它会按顺序把下面这些子技能跑一遍最后汇总成一份问题清单。这个设计的好处是你既可以一键跑全量也可以单独调用某个子技能做专项检查。场景层的 7 个技能我按「审查对象」分成三组来讲这样更好记。第一组是设计契约与系统层管的是「设计规则本身对不对」。design-md-review负责审查或编写 DESIGN.md 设计契约文件重点验证 token 完整性——比如你定义了color.primary但代码里出现了没登记的#2563EB它就能揪出来。design-system-capture则是从代码、截图或 Figma 中反向捕获设计系统规则适合那些还没有正式设计系统、想先沉淀一份的项目。第二组是实现对齐层管的是「代码实现和设计参考对不对得上」。ui-alignment-review检查 UI 实现是否与批准的设计参考图对齐这是最贴近日常走查的技能。visual-regression-review做截图对比检测 UI 视觉回归适合接入 CI 做每次提交的自动比对。component-library-alignment检查是否使用了指定的设计系统组件库——比如团队规定按钮只能用Button组件结果有人手写了个div classbtn它就能发现。第三组是质量与体验层管的是「除了对齐还有没有别的坑」。accessibility-review做无障碍审查覆盖键盘操作、屏幕阅读器、低视力等场景。design-debt-review检测设计债务专门抓硬编码颜色、一次性变体、token 漂移这些「当时图快、后面还债」的问题。responsive-design则关注响应式布局实现包括容器查询、流体排版等。再看 Canvas。它目前只有一个画布查看器design-mdCanvas作用是把 DESIGN.md 文件渲染成交互式的设计系统摘要视图。别小看这一个画布——设计契约文件写成 Markdown 后纯文本读起来枯燥评审时没人愿意逐行看。渲染成可视化摘要后颜色、字号、间距这些 token 一目了然评审效率会高很多。把两者放一起看分工就很清晰了Skills 是审查的执行引擎Canvas 是审查结果的呈现层。Skills 跑完产出的问题清单是给机器和开发者看的Canvas 渲染的设计系统摘要则是给设计和评审团队看的。一个管「查得全」一个管「看得懂」。这里有个容易踩的坑很多人以为 Canvas 是审查工具其实它不参与审查逻辑只做渲染。审查的准确性完全取决于 Skills 的规则配置。所以下一步的重点是把 Skills 的配置和审查规则模板搭起来。3. 可复制的插件配置清单与审查规则模板这一节是整篇最实操的部分。我会给出可复制的配置片段路径和字段名尽量贴近真实插件的结构。需要提醒的是Design Review 插件不含 MCP 服务器所以配置的重点不在 MCP 连接而在技能启用清单和审查规则模板两件事上。先看技能启用配置。这份配置决定了一次审查要跑哪些技能、按什么顺序跑。我把它写成一个 JSON 片段你可以直接放进项目的插件配置目录里{ designReview: { version: 1.0, orchestrator: design-qa, skills: { design-md-review: { enabled: true, strict: true }, ui-alignment-review: { enabled: true, referenceDir: ./design/refs }, visual-regression-review: { enabled: true, threshold: 0.02 }, accessibility-review: { enabled: true, level: AA }, component-library-alignment: { enabled: true, library: internal-ui }, design-debt-review: { enabled: true, failOnHardcodedColor: true }, design-system-capture: { enabled: false }, responsive-design: { enabled: true, breakpoints: [375, 768, 1280] } }, canvas: { design-mdCanvas: { enabled: true, source: ./DESIGN.md } } } }几个字段值得单独说。orchestrator指定编排器为design-qa这是跑全量的入口。strict: true表示design-md-review遇到 token 缺失直接报错而不是警告。threshold: 0.02是视觉回归的像素差异容忍度2% 以内算通过这个值要根据项目实际调整——太严会天天误报太松又抓不到问题。failOnHardcodedColor: true让design-debt-review在发现硬编码颜色时直接判定失败适合对设计系统要求严格的团队。design-system-capture我默认关掉了因为它更适合一次性沉淀不适合每次审查都跑。接下来是审查规则模板。这份模板定义「什么算问题、问题的严重级别是什么」是 Skills 判断的依据。我用 TOML 写一份放在./design/review-rules.toml[meta] name frontend-design-review version 1.0 [token] # 设计 token 白名单未登记的视为漂移 colors [#2563EB, #1E40AF, #F8FAFC, #0F172A] spacing [4px, 8px, 12px, 16px, 24px, 32px] radius [4px, 8px, 12px, 9999px] fail_on_unknown true [alignment] # 与设计参考图对齐的容忍度 max_offset_px 2 check_spacing true check_typography true [accessibility] level AA require_alt_text true min_contrast_ratio 4.5 keyboard_navigable true [debt] # 设计债务检测项 hardcoded_color error one_off_variant warning token_drift error inline_style warning [responsive] require_container_query true fluid_typography true这份模板里[token]段是核心。colors列出允许使用的颜色fail_on_unknown true表示出现白名单外的颜色就报错。[alignment]段的max_offset_px 2和前面 JSON 里的视觉回归阈值是两回事——前者管的是元素位置偏移后者管的是截图整体差异。[accessibility]段把对比度要求定在 4.5这是 WCAG AA 的标准值。[debt]段给不同债务类型分了级别硬编码颜色和 token 漂移是 error一次性变体和内联样式是 warning。如果你用的是 Claude Code 这类支持 settings 文件的工具可以把插件配置挂到 settings 里路径保持和项目结构一致{ plugins: { design-review: { configPath: ./.design-review/config.json, rulesPath: ./design/review-rules.toml, canvasSource: ./DESIGN.md } } }这里要强调一个原则Base URL、Key、Model ID 这三件套在 Design Review 里不是必须的因为插件本身不依赖外部模型服务就能跑规则审查。但如果你想让design-md-review或design-debt-review具备语义理解能力比如判断一段文案是否符合设计语气那就需要接入模型服务。这时候三件套要写全Base URL 指向服务地址Key 用你的 API KeyModel ID 指定具体模型。缺任何一个语义类技能都会报错。配置搭好后建议先只开design-md-review和design-debt-review两个技能跑一次确认规则模板能被正确解析再逐步放开其他技能。一次性全开容易因为某个技能配置不对导致整条链路失败排查起来很费劲。4. 从触发审查到输出问题清单的完整验证配置就绪后最关键的验证动作是跑一次完整审查看它能不能从触发走到输出问题清单。这一节我把过程拆成可跟做的步骤每一步都说明预期结果。第一步准备一个「有问题」的测试页面。审查工具最怕的是「跑完啥也没报」你分不清是真没问题还是没生效。所以先故意埋几个坑把某个按钮的颜色写成#3B82F6不在 token 白名单里把一段间距写成10px不在 spacing 列表里再给一张图片去掉alt属性。这样跑完如果没报出来就说明配置有问题。第二步触发编排器。调用design-qa技能让它按配置顺序跑所有启用的子技能。触发方式取决于你的工具环境通常是通过技能调用入口传入项目路径和配置文件路径。预期结果是编排器开始逐个执行技能并在控制台输出每个技能的执行状态。第三步观察各技能的输出。design-md-review应该报告 token 缺失指出#3B82F6未登记design-debt-review应该把硬编码颜色标为 erroraccessibility-review应该报告图片缺少 alt 文本。如果某个技能没输出先检查它在配置里是否enabled: true。第四步查看 Canvas 渲染结果。打开design-mdCanvas它会把 DESIGN.md 渲染成交互式摘要。预期结果是你能看到颜色、间距、圆角等 token 的可视化展示并且缺失或异常的 token 会有标记。这一步是给评审团队看的确认设计契约本身是否完整。第五步汇总问题清单。编排器跑完后会输出一份结构化的问题清单通常包含问题类型、位置、严重级别和建议修复方式。我实测下来一份中等规模页面的审查能在几十秒内跑完输出的问题清单可以直接贴进 issue 或 PR 评论里。这里给一个预期输出的示意帮你判断结果是否正常[design-qa] 审查完成共发现 3 个问题 1. [error] design-debt-review: 硬编码颜色 #3B82F6 at src/components/Button.tsx:12 建议: 替换为 token color.primary (#2563EB) 2. [error] design-md-review: 未知间距值 10px at src/components/Card.tsx:28 建议: 使用 spacing 白名单中的 8px 或 12px 3. [error] accessibility-review: 图片缺少 alt 文本 at src/components/Banner.tsx:5 建议: 补充描述性 alt 属性看到类似输出就说明整条链路通了。如果问题清单是空的回到第一步检查测试页面是否真的埋了坑以及规则模板里的白名单是否把#3B82F6意外包含了进去。验证通过后你可以把这次审查的配置和规则模板固化下来作为团队的标准审查流程。后续每次发版前跑一次或者接入 CI 在 PR 阶段自动触发设计质量审查就从「靠人盯」变成了「有流程可依」。5. 常见报错排查401、local proxy failed 与 reading choices跑这套工作流时报错基本集中在几类。我把最常见的几个列出来对照着排查会快很多。401 未授权。这个报错通常出现在需要模型服务的技能上比如design-md-review做语义判断时。原因无非三种Key 没填、Key 填错、Key 对应的服务地址不对。排查顺序是先确认配置文件里 Key 字段非空再确认 Base URL 和 Key 是配套的——用 A 服务的 Key 去请求 B 服务的地址必然 401。如果三件套里 Model ID 也填了还要确认这个模型 ID 在对应服务里是存在的。local proxy failed。这个报错和网络代理配置有关。Design Review 插件本身不强制走代理但如果你的环境里配置了本地代理而代理服务没启动或端口不对就会报这个。排查方法是检查环境变量里的代理设置确认代理服务在运行。如果不需要代理把相关环境变量清掉再试。注意这里说的是本地开发环境的代理配置问题和任何网络访问方式无关纯粹是配置层面的排查。reading choices 报错。这个通常出现在模型返回结果解析阶段。choices是模型响应里的字段如果返回结构不符合预期解析就会失败。常见原因是模型返回了空内容或者返回格式和技能预期的格式不一致。排查时先看原始响应内容确认模型确实返回了有效结果如果返回为空检查请求参数里的 max tokens 是否设得太小导致内容被截断。OAuth 相关报错。如果插件依赖的某个服务用 OAuth 鉴权token 过期或 scope 不足都会报错。排查方法是重新走一遍授权流程确认授予的权限范围覆盖了插件需要的操作。这类报错的特点是提示里通常带scope或token expired字样比较好识别。技能未执行。这个不算报错但很常见配置里明明开了某个技能跑完却没输出。先检查技能名拼写是否和插件定义的一致大小写和连字符都不能错。再检查编排器的执行顺序有些技能依赖前置技能的输出前置没跑成功后面的会被跳过。Canvas 渲染空白。design-mdCanvas渲染不出来多半是 DESIGN.md 路径不对或文件格式有问题。确认配置里的source路径指向真实存在的文件再检查 Markdown 结构是否符合画布解析要求——比如 token 定义是否用了它认识的标题层级。排查这类问题的通用思路是先定位是配置问题还是服务问题。配置问题看字段名、路径、拼写服务问题看鉴权、网络、返回格式。把这两类分开大部分报错都能在几分钟内定位。6. 把设计审查接进日常流程的几个实用建议跑通一次审查只是开始真正有价值的是把它变成日常习惯。分享几个我踩过坑之后总结的做法。第一规则模板要渐进式收紧。一开始别把fail_on_unknown设成 true否则历史代码里的存量问题会一次性全爆出来团队会被淹没。先设成 warning跑一段时间把存量清得差不多了再切成 error。设计债务的清理是个过程不是一次性的。第二视觉回归阈值要按页面调。threshold: 0.02是个通用起点但营销页和后台表格页的容忍度完全不同。营销页动效多、图片多阈值可以放宽到 0.05后台页以静态表格为主0.01 就够。一刀切的结果是要么误报太多没人看要么漏报太多没意义。第三Canvas 渲染的设计系统摘要要定期评审。它不只是给机器看的更是设计和前端对齐认知的载体。建议每个迭代周期拉一次评审确认 token 有没有新增、有没有废弃。设计系统是活的不是写完就锁死的。第四问题清单要能落到具体的人。审查输出的是问题但修复要靠人。把问题清单和代码行号绑定直接生成 issue 或 PR 评论比丢一份报告到群里有效得多。谁改哪一行一目了然。第五别指望它替代人工走查。Skills 能抓 token 漂移、硬编码、无障碍这些可规则化的问题但「这个交互手感对不对」「这个动效节奏舒不舒服」这类判断还是得靠人。把它当成走查的预处理先让机器把机械性问题清掉人专注在体验判断上效率才是真的提升。如果你想把模型能力也接进来做语义级审查可以到 TaoToken 模型对话 先验证一下模型对设计文案的理解效果确认可用后再写进配置。需要长期跑编码和 Agent 类任务的可以看看 Coding Plan把审查流程和日常开发串起来。配置过程中要生成和管理 Key 的入口在 API Keys具体的接入参数和字段说明可以对照 接入文档 来填避免字段名写错导致技能跑不起来。