asdesigned

asdesigned

是否符合设计？将渲染后的 UI 组件与其 Figma 源文件进行对比，准确查看偏差之处。 专为编码 Agent 打造：将工具交给 Claude Code 或 Cursor，它们就能对照设计检查自己的工作。

asdesigned compare https://www.figma.com/design/<key>/<file>?node-id=12-345 \
      --url http://localhost:3000 --selector .btn-primary

design   figma  Button / Primary  1:4
rendered dom  <button class="btn-primary">  .btn-primary

box
  ✗ width          design 120px → rendered 112px (−8px)
padding
  ✗ left           design 16px → rendered 12px (−4px)
  ✗ right          design 16px → rendered 12px (−4px)
border
  ✗ color          design #1d4ed8 → rendered #2563eb (Δ29.43)
typography
  ✗ fontFamily     design "Inter" → rendered "Arial"
  ✗ fontWeight     design 600 → rendered 500 (−100)

6 drift · 20 match
FAIL  (tolerance ±1px, color Δ≤4)

这个结果确实如此——用真实的 Figma 组件对比 examples/button.html 得出的结果。六处差异中有五处是故意设置的。 第六处不是：<button> 元素不会继承 font-family，所以页面悄悄回退到了 Arial。 截图审查时没人能发现这一点，但差异报告可以。

Figma 呈现设计意图，浏览器呈现实际效果。asdesigned 会比较两者，而你的编码 Agent 可以调用它来检查自己的工作。

状态：v0.2 — 早期版本，已可使用。 Figma → 规范、DOM → 规范、差异对比、终端 + HTML 报告、MCP 服务、 交互状态。每次运行只能处理一个视口——请参阅检查范围及不检查的内容。

安装

npx asdesigned --help            # no install
npm i -g asdesigned              # or install the `asdesigned` command globally
npx playwright install chromium   # one-time: the browser used to render pages

在环境变量或 .env 文件中设置 FIGMA_TOKEN（具有 file content: read 权限的 Figma 个人访问令牌）。

从 Agent 调用（MCP）

asdesigned 内置 MCP 服务，Claude Code、Cursor 和其他 MCP 客户端都可以直接调用。 工具：compare_design、inspect_element、inspect_figma。 这三个工具都支持状态：compare_design 接受 states: ["default","hover","focus"]，inspect_element 接受单个 state，而 inspect_figma 接受 variants: true，用于列出组件集所包含的设计变体。

Claude Code — 项目中的 .mcp.json：

{
  "mcpServers": {
    "asdesigned": {
      "command": "npx",
      "args": ["-y", "asdesigned", "asdesigned-mcp"],
      "env": { "FIGMA_TOKEN": "figd_…" }
    }
  }
}

Cursor — .cursor/mcp.json，格式相同。

说明 Agent 何时以及如何调用该工具的技能文件位于 skills/asdesigned/SKILL.md — 将它放入 Agent 的技能文件夹即可。

从终端使用

asdesigned compare <figma-url> --url http://localhost:3000 --selector .btn-primary
asdesigned compare <figma-url> --url … --selector … --states hover,focus  # interaction states
asdesigned compare <figma-url> --url … --selector … --html report.html   # self-contained visual report
asdesigned compare <figma-url> --url … --selector … --json               # for CI / scripts
asdesigned inspect http://localhost:3000 --selector .btn-primary
asdesigned inspect http://localhost:3000 --selector .btn --state hover   # one rendered state
asdesigned inspect <figma-url> --variants                                # what states are designed

交互状态

--states hover,focus,active,disabled（或 --states all）会将每个状态作为独立部分进行对比。

读取计算样式前，渲染端会强制匹配对应的伪类——同时检查 :focus 和 :focus-visible，以免遗漏现代焦点环。设计端的数据来自 Figma 组件集的变体：State=Hover、State=Focused，以及设计师使用的其他写法 （Pressed、Rest、Inactive）都会被识别。可以指定组件集或其中任意一个变体；asdesigned 会沿着 componentSetId 查找同级变体。

Button / Primary  3 variants  1:10

default  1 drift  figma  State=Default  1:11
  border
    ✗ color          design #1d4ed8 → rendered #2563eb (Δ29.43)
  1 drift · 20 match

hover    no drift  figma  State=Hover  1:12
  0 drift · 21 match

focus    skipped  "Button / Primary" has no focus variant (it defines: default, hover) — nothing to compare against

1 drift · 41 match · 2 states compared · 1 skipped
FAIL

设计中未定义的状态会跳过，而非判定失败——asdesigned 不会凭空编造预期值。这个跳过本身也值得关注：没有 Focused 变体，意味着设计中从未定义焦点环，这是设计文件中的缺失，而不是代码错误。如果请求的所有状态在设计中都未定义，运行结果会报告 NOTHING COMPARED 并以非零状态码退出，因此状态检查不会因什么都没检查而悄悄通过。

发现偏差时，退出码为 1，因此 compare 可用作 CI 检查。

工作原理

两侧都会被规范化为一个扁平的 StyleSpec——以 px 表示的数值、RGBA 颜色，且每个字段都是可选的；然后通过纯 diff 按合理的容差（±1px、较小的颜色差异、字体粗细零容差）进行比较。 一侧缺失的字段会被报告，但不会导致本次运行失败；只有实际偏差才会导致失败。

交互状态原样复用以上所有机制：一个状态就是一对 spec，因此 diff 无需专门处理交互状态。

• src/spec.ts — 共享格式
• src/diff.ts — 比较逻辑
• src/states.ts — 状态词汇表和 Figma 变体→状态匹配
• src/compare.ts — 每个状态的比较，以及状态未在设计中定义时的提示
• src/readers/figma.ts — Figma REST → spec，包括组件集变体
• src/readers/dom.ts — Playwright 计算样式 → spec，通过 CDP 强制应用伪类
• src/report.ts、src/report-html.ts — 输出

检查内容——以及不检查的内容

asdesigned 会在一个视口下，将一个设计节点与一个渲染元素进行比较，并检查你指定的 UI 状态。 这涵盖了最常见的偏差：内边距、尺寸、颜色，以及上文提到的 Arial 回退这类继承字体错误——还包括通过 --states 检查 hover、focus、active 和 disabled 状态。

交互状态有一项要求，值得明确说明：设计必须将它们定义为变体。 具有 State=Hover 的组件集可以解析；而扁平画板，或 hover 仅作为原型交互存在的文件，都无法提供可供 asdesigned 比较的内容，因此会跳过该状态。检查前，inspect <figma-url> --variants 会告诉你组件实际设计了哪些状态。

未涵盖的内容：

• 重排。 一次运行只会在一个视口下渲染——默认使用 --viewport WxH，尺寸为 1280×800。要检查组件在不同断点下的表现，需要针对每个断点各运行一次 compare，并分别与设计师为其绘制的画板进行比较。没有一个命令可以一次遍历所有断点。
• 动效。 不会比较过渡时长和缓动，因此只检查状态的最终值，不检查它如何达到该状态。
• 任何不是计算样式的内容。 相对于相邻元素的布局、内容和行为均不在范围内。

还有一条不属于路线图事项的界限：设计的断点之间不存在设计依据。 如果文件中有一个 768 画板和一个 1280 画板，其中没有任何内容规定 900px 时应当是什么样。asdesigned 可以告诉你组件在某个经过设计的宽度下出现了偏差——但无法判断两个断点之间的情况。任何将设计视为事实来源的工具都做不到这一点。

开发

npm install
npm test
npm run build
node dist/cli.js --help

ASDESIGNED_BROWSER=/path/to/chrome 使用现有的 Chrome/Chromium，而不是下载 Playwright 的浏览器。

与其他工具的关系

• Figma 的 MCP 服务为 Agent 提供设计。Chrome DevTools MCP为 Agent 提供浏览器。asdesigned 补上了两者之间缺失的动词：比较。
• 视觉回归工具（Percy、Chromatic、像素差异工具）会将应用的截图与应用较早的截图进行比较。asdesigned 会将应用与设计进行比较，并报告属性而非像素——因此结果是待修复的问题，而不是热力图。
• design-drift 也在探索类似方向，提供像素 + 元素差异比较和查看器。asdesigned 刻意做得更精简——一个动词、以 Agent 为先、23 kB。

许可证

MIT