디자인 시스템 문서와 실제 제품이 다르다면, 이 도구가 정확히 어디가 다른지 보여줍니다.

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

두 개의 소스만 주면 됩니다 — 디자인 도구 내보내기(Figma, Sketch, Penpot, Tokens Studio…), 라이브 사이트나 웹 앱 URL, 코드베이스 토큰 파일 — 그러면 실제 드리프트 보고서를 출력합니다. 사이트 URL은 실시간으로 스캔되며(추출은 오픈소스 Dembrandt 추출기에 위임), 설정할 것도 없고 준비된 것도 없습니다: 보고서는 지금 이 순간 존재하는 실제 디자인 시스템 그 자체입니다.

인자가 없나요? npx token-reconciler를 실행하면 안내형 시작 모드가 열려 단계별로 안내해 줍니다.

문제

디자인 시스템은 한 곳에만 존재하지 않습니다. Figma 파일, 배포된 CSS, 코드베이스 — 동일한 결정의 세 가지 사본이 있습니다. 시간이 지나면서 이들은 조용히 서로 어긋나기 시작합니다: 개발자가 브랜드 인디고 대신 Tailwind의 파란색을 하드코딩하고, Figma에 새 회색이 추가되었지만 배포되지 않으며, 타이포그래피 스케일이 600이라고 하는데 헤딩이 700으로 나갑니다. 어떤 단일 도구도 이를 감지하지 못합니다. 각 도구는 자신의 사본만 보기 때문입니다.

2026년까지 추출 측면은 해결되었습니다 — 훌륭한 오픈소스 도구들이 라이브 사이트에서 토큰을 뽑아내고, Figma는 Variables를 내보내며 — 모두 동일한 DTCG 형식(W3C Design Tokens Community Group 표준: 디자인 토큰을 위한 하나의 합의된 JSON 형태로, 모든 도구가 다른 도구의 출력을 읽을 수 있게 함)을 사용합니다. 빠져 있던 것은 그 다음 단계였습니다: 이 파일들을 비교하고 어떤 차이가 중요한지 아는 것. 이 도구가 바로 그 일을 합니다.

Related MCP server: Figma MCP Server by Bao To

제공 기능

비교를 실행하면 세 개의 섹션이 있는 보고서가 생성됩니다:

• 충돌(Conflicts) — 두 소스에서 동일한 토큰이 다르게 정의된 경우, 차이가 얼마나 중요한지에 대한 0–1 신뢰도 점수로 정렬됩니다. 점수는 유형을 인식합니다: 색상은 문자열이 아닌 지각적으로(OKLab) 비교됩니다 — 따라서 #FFFFFF vs rgb(255,255,255)는 아닌 충돌이며, 한 단계 차이 나는 두 회색은 충돌입니다. 치수와 지속 시간은 단위가 정규화되고(1rem = 16px, 0.3s = 300ms), DTCG 별칭은 비교 전에 해석되므로 {color.base.indigo.500}와 원시 값이 일치합니다.

• 매칭되지 않은 토큰(Unmatched tokens) — 설계되었지만 배포되지 않았거나, 배포되었지만 설계되지 않은 토큰. 아직 충돌은 아니지만, 보통 다음 충돌이 발생하는 지점입니다.

• 충돌별 제안된 해결 방안 — 의도적으로 단순한 기본 리졸버(mostRecentWins)에서 제공되며, 그 근거가 명시됩니다. 더 정교한 해결은 플러그인 방식으로 교체 가능합니다.

• 접근성 분석, 현재 및 차기 표준 — 텍스트 역할 색상 토큰이 배경 역할 토큰과 짝지어 WCAG 2.2 AA(4.5:1 — 현재 W3C 표준이자 EU 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. 디자인 시스템의 토큰을 보유한 도구에서 DTCG JSON으로 내보냅니다 — Figma(커뮤니티 플러그인 "Design Tokens (W3C)" 또는 DesignBridge), Penpot(기본 DTCG 내보내기), Sketch, 또는 Tokens Studio.

2. 실행:

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

두 소스 비교하기 — 모든 인자는 .json 파일 경로, 토큰 파일 URL, 또는 스캔할 사이트 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, 웹 앱, 모바일 앱

디자인 시스템은 주로 공개 웹사이트가 아닌 제품에 존재합니다. 모든 종류의 제품이 연결됩니다 — 소스만 다를 뿐입니다:

로그인 필요 SaaS / 웹 앱. 여전히 웹이므로 스캐너가 세션만 있으면 됩니다. 브라우저 개발자 도구(Application → Cookies)에서 쿠키를 가져와 전달하세요:

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

토큰 인증 앱에는 --header "Authorization: Bearer …"도 사용할 수 있습니다. 중요한 화면의 URL을 직접 지정하여 스캔하세요.

모바일 앱(iOS / Android / React Native / Flutter). 스캔할 URL이 없습니다 — 하지만 모바일 앱의 디자인 토큰은 코드베이스에 존재하며, 이는 스캔보다 더 좋습니다: Android Compose/XML 테마, iOS 에셋 카탈로그, React Native 테마 파일. Style Dictionary 또는 Tokens Studio를 사용한다면 소스 토큰 JSON이 이미 DTCG 호환입니다 — 직접 입력하세요:

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

이 코드베이스-소스 방식은 웹 앱에서도 가장 정확한 경로입니다. 스캔된 계산 스타일보다 의도된 코드 토큰을 비교하고 싶을 때 사용합니다.

세 가지를 동시에. 이 도구는 2개 이상의 소스를 받습니다 — 따라서 한 번의 실행으로 "Figma, 웹 앱, 그리고 모바일 테마가 일치하는가?"에 답할 수 있습니다:

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

세 가지 도구: reconcile(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 — 가장 최신 추출이 승리, 타임스탬프가 없으면 기권), 자체 리졸버 작성은 함수 하나입니다:

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 플러그인의 역할입니다. 이 도구는 추출기가 멈춘 지점에서 시작합니다.

• 발명된 스키마 없음. 표준 DTCG 입력, 표준 DTCG 개념 출력.

• 가짜 판단 없음. 기본 리졸버는 자신이 단순하다는 것을 정직하게 인정합니다. 실제 판단 — 당신의 시스템 의도를 아는 것 — 은 별개의 제품입니다.

함께 사용하면 좋은 도구

• Dembrandt — 라이브 사이트 → DTCG 토큰; 이 도구의 URL 스캔을 지원합니다.

• designlang — 라이브 사이트 → 토큰 + 레이아웃 + 접근성 데이터 (GitHub).

• uiscanner — URL → MCP를 통한 토큰 분석.

• DesignBridge — Figma 디자인 시스템 → 구조화된 DESIGN.md + 토큰.

• W3C DTCG 형식 — 이 모든 것을 구성 가능하게 만드는 상호 교환 형식.

개발

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

라이선스

Apache-2.0. 사용하고, 포크하고, 이를 기반으로 제품을 만드세요.

wildchild.ai가 제작했습니다.