你的设计系统说的是一套，产品实际交付的却是另一套。这里精确地告诉你差在哪里。

npx token-reconciler ./design-tokens.json https://yourproduct.com

把任意两个来源交给它——设计工具的导出（Figma、Sketch、Penpot、Tokens Studio…）、实时站点或 Web 应用的 URL、代码库中的 token 文件——它就会输出一份真实的漂移报告。站点 URL 是实时扫描的（提取工作由开源的 Dembrandt 提取器完成），因此无需任何配置，也没有任何暂存内容：这份报告就是你的设计系统此刻的真实状态。

没有参数？运行 npx token-reconciler 就会进入一个引导式启动流程，带你一步一步完成。

问题所在

设计系统绝不会只存在于一个地方。这里有 Figma 文件、已交付的 CSS、还有代码库——同一套决策的三份拷贝。随着时间推移，它们会悄无声息地开始互相背离：某个开发者把 Tailwind 的蓝色硬编码了进去，而不是用品牌靛蓝；Figma 里多了一个从未做出出现的灰色；一个标题最终以 700 发布，而不是排版规范中的 600。没有哪个单一工具会发现这些，因为每个工具只看到自己的那一份。

到 2026 年，提取这一环已经解决了——优秀的开源工具能从真实发布的产品站点里抽出 token，Figma 也能导出 Variables——它们都在说同一种 DTCG 格式（W3C Design Tokens Community Group 标准：为设计 token 定义一种统一的 JSON 结构，让每个工具都能读取任意其他工具的输出）。真正被遗漏的是下一步：比较这些文件，知道哪个差异重要。 这正是这个工具要做的事。

Related MCP server: Figma MCP Server by Bao To

你会得到什么

运行一次比较，会得到一份包含以下三个部分的报告：

• 冲突——同一个 token 在两个来源中定义不同，按 0–1 的置信度分数排序，该分数表示差异的重要程度。评分是类型感知的：颜色按感知方式（OKLab）比较，而不是按字符串比较——所以 #FFFFFF 和 rgb(255,255,255) 不 构成冲突，而两个只差一个色阶的灰则构成冲突。尺寸和时长会先做单位归一化（1rem = 16px，0.3s = 300ms），DTCG 别名也会在比较前解析，因此 {color.base.indigo.500} 和它的原始值是一致的。

• 未匹配的 token——被设计出来但从未上线，或已上线但从未被设计。它们还不是冲突，但通常就是下一个冲突的诞生地。

• 每个冲突的解决建议——由一个刻意保持简单的默认解析器（mostRecentWins）给出，并存它的理由。更聪明的解决方案是可插拔的。

• 可访问性分析——现在的标准和下一代标准——文字角色的颜色 token 与背景角色的 token 两两配对，并按 WCAG 2.2 AA（4.5:1——当前 W3C 标准，也是欧盟 EAA / ADA 规则绑定的等级）逐对检查，同时也给出 AAA 和APCA 的可参考读数（WCAG 3.0 草案算法）。它的独特之处在于：因为这个工具能看到多个来源，它可以告诉你漂移是否改变了可访问性——同一对配对在 Figma 里通过 AA，在真实上线站点上却失败。普通审计做不到这一点；能对账的工具可以。

这里是某一次真实运行给出的片段（两个生产环境站点，实时扫描）：

### typography.style.text-heading-1
Confidence: 0.97 🔴 · type: typography

| Source        | Value                                                    |
|---------------|----------------------------------------------------------|
| wildchild.ai  | { fontFamily: Geist, fontSize: 48px, fontWeight: 400 … } |
| humano.ai     | { fontFamily: Inter, fontSize: 12px, fontWeight: 700 … } |

### color.palette.palette-3
Confidence: 0.94 🔴 · type: color
| wildchild.ai  | #7a7a7a |
| humano.ai     | #888888 |

如何使用

拿你的设计系统去对比你的产品（核心场景）：

1. 从任何保留这些 token 的工具中，把设计系统的 tokens 导出为 DTCG JSON——Figma（“Design Tokens (W3C)”或 DesignBridge 等社区插件）、Penpot（原生 DTCG 导出）、Sketch 或 Tokens Studio。

2. 运行：

npx token-reconciler ./design-tokens.json https://yourproduct.com

比较任意两个来源——每个参数都可以是一个 .json 文件路径、一个指向 token 文件的 URL，或一个待扫描站点：

npx token-reconciler https://yoursite.com https://staging.yoursite.com
npx token-reconciler design-system.tokens.json codebase-scan.tokens.json

引导模式——如果不确定从哪里开始：

npx token-reconciler

在 CI 中——给命退出码本身就是漂移门禁（0 无事发生，1 存在高风险冲突，2 输入错误）：

npx token-reconciler reconcile figma.tokens.json site.tokens.json --threshold 0.7 --out report.md

常用参数：--json（JSON 报告）、--out <file>、--names a,b、--kinds figma-variables,live-site、--threshold <0..1>、--no-fail。完整的 GitHub Actions 配置见 examples/ci-usage.md，逐段讲解见 examples/dembrandt-vs-figma.md。

不只是官网：SaaS、Web 应用与移动应用

设计系统大部分诞生在产品内部，而不是内容公开官网。所有类型的产品都能接入——差别只是来源：

需要登录的 SaaS / Web 应用。 它仍然走 Web；扫描器只不过需要你的会话。从浏览器调试工具（Application → Cookies）取出 cookie，传给它即可：

npx token-reconciler ./design-tokens.json https://app.yourproduct.com --cookie "session=abc123"

--header "Authorization: Bearer …" 也可以这样用——适用于用 token 认证的应用。直接给多个你关心的界面它的 URL，然后扫描即可。

移动应用（iOS / Android / React Native / Flutter）。 这里没有 URL 可扫——但设计 tokens 就存在于代码库中，这比扫描更好：Android Compose/XML 主题、iOS 资源目录、React Native 主题文件。如果你使用 Style Dictionary 或 Tokens Studio，你的 token JSON 天然兼容 DTCG——直接喂给它：

npx token-reconciler ./design-tokens.json ./mobile-app/tokens/theme.tokens.json

这种“把代码库当来源”的方式也是给 Web 应用对最精确的选择，尤其是当你更想比较预期的代码 token，而不只是扫描出来的计算样式。

同时比较三端。 该工具接受 2 个或更多来源——因此一个命令就能回答：Figma、Web 应用和移动端主题，它们同步一致吗？

npx token-reconciler design-tokens.json https://app.yourproduct.com android/tokens.json

从 AI 智能体中使用（MCP）

claude mcp add token-reconciler -- npx -y token-reconciler-mcp

三类工具：routealign(sources) 执行对比并返回带评分的报告；get_conflicts(runId) 获取历史运行；explain_conflict(runId, tokenPath) 把单个冲突完整拆解——各来源的原始值和最终值、别名链，以及每一个置信度因子并带权重和推理过程。它和提取类 MCP 服务器配合得得心应手：智能体可以在同一次会话中用 Dembrandt 扫描网站，再与 Figma 导出的数据对账。

作为库使用

import { reconcileSources } from "token-reconciler";

const report = await reconcileSources([
  { name: "Design system", kind: "design-tool", document: "./design.tokens.json" },
  { name: "Live site", kind: "live-site", document: "./site.tokens.json" },
]);

for (const conflict of report.conflicts) {
  console.log(conflict.path, conflict.confidence.score, conflict.confidence.factors);
}

document 接受一个文件路径、一个 http(s) URL，或一个已经解析的 DTCG 对象。如果某个来源在 $extensions 带有提取时间戳（Dembrandt 就是这么做的），它会被自动识别。

置信度分数是怎么算的

每个冲突的得分来自三个有据可查的因子——完整细节会随报告给出，绝不会像黑箱：

理论上分数上限约 0.97：因为我们知道这是启发式；而真正的启发式不会给出 1.00 的假确值。

接入自定义解析器

检测冲突是这个库的本职；决定谁是获胜方 则好可插拔。目前内置一个刻意简单的解析器（ mostRecentWins —— 总是选时间戳最新的提取，没有时间戳时弃权）。写一个自己的 function 很简单：

import type { Resolver } from "token-reconciler";

const designWins: Resolver = (conflict) => {
  const design = conflict.sightings.find((s) => s.sourceKind === "design-tool");
  if (!design) return { decision: "unresolved", reasoning: "no design-tool source" };
  return {
    decision: "resolved",
    winner: design.sourceName,
    value: design.token.resolvedValue,
    reasoning: "design file is the declared source of truth",
  };
};

每次解析都会附带 reasoning 字符串，从未例外。来源完整可溯，永远如此。

边界范围——以及刻意不做的事

• 没有自己的提取引擎。 站点扫描交给了 Dembrandt；Figma 导出属于 Figma 插件。这个工具从提取器结束的地方开始。

• 不发明新的 schema。 标准 DTCG 进来，标准 DTCG 概念输出。

• 不假装有判断力。 默认解析器对自己很不起的直率。真正的判断——摄入理解你的系统的意图——是属于另一个产品的事。

这些工具配合得很好

• Dembrandt — 实时站点 → DTCG tokens；为本工具的 URL 扫描提供能力。

• designlang — 实时站点 → tokens + 布局 + 辅助功能数据（GitHub）。

• uiscanner — URL → 通过 MCP 做 token 拆解。

• DesignBridge — Figma 设计系统 → 结构化 DESIGN.md + tokens。

• W3C DTCG format — 让以上所有环节可以组装对待的交换格式。

开发

npm install
npm run build   # tsc → dist/
npm test        # vitest — includes an end-to-end MCP client/server test

License

Apache-2.0。放心使用、fork 它，并在这之上构建产品。

由 wildchild.ai 创造。