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 class="btn">，它就能发现。
第三组是质量与体验层，管的是「除了对齐，还有没有别的坑」。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 Key，Model ID 指定具体模型。缺任何一个，语义类技能都会报错。
配置搭好后，建议先只开design-md-review和design-debt-review两个技能跑一次，确认规则模板能被正确解析，再逐步放开其他技能。一次性全开容易因为某个技能配置不对导致整条链路失败，排查起来很费劲。
4. 从触发审查到输出问题清单的完整验证
配置就绪后，最关键的验证动作是：跑一次完整审查，看它能不能从触发走到输出问题清单。这一节我把过程拆成可跟做的步骤，每一步都说明预期结果。
第一步，准备一个「有问题」的测试页面。审查工具最怕的是「跑完啥也没报」，你分不清是真没问题还是没生效。所以先故意埋几个坑：把某个按钮的颜色写成#3B82F6（不在 token 白名单里），把一段间距写成10px（不在 spacing 列表里），再给一张图片去掉alt属性。这样跑完如果没报出来，就说明配置有问题。
第二步，触发编排器。调用design-qa技能，让它按配置顺序跑所有启用的子技能。触发方式取决于你的工具环境，通常是通过技能调用入口传入项目路径和配置文件路径。预期结果是：编排器开始逐个执行技能，并在控制台输出每个技能的执行状态。
第三步，观察各技能的输出。design-md-review应该报告 token 缺失，指出#3B82F6未登记；design-debt-review应该把硬编码颜色标为 error；accessibility-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，具体的接入参数和字段说明可以对照 接入文档 来填，避免字段名写错导致技能跑不起来。