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 Console MCP Server
비교를 실행하면 세 개의 섹션이 있는 보고서가 생성됩니다:
충돌(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 |디자인 시스템과 제품 비교하기(핵심 기능):
디자인 시스템의 토큰을 보유한 도구에서 DTCG JSON으로 내보냅니다 — Figma(커뮤니티 플러그인 "Design Tokens (W3C)" 또는 DesignBridge), Penpot(기본 DTCG 내보내기), Sketch, 또는 Tokens Studio.
실행:
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-reconcilerCI에서 — 종료 코드가 드리프트 게이트 역할을 합니다(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 / 웹 앱. 여전히 웹이므로 스캐너가 세션만 있으면 됩니다. 브라우저 개발자 도구(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.jsonclaude 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.6 | 유형 인식 거리. 색상은 지각적(OKLab), 치수/지속 시간은 상대적 수치, 복합체는 필드 평균. 중간 범위 델타가 가장 높은 점수를 받습니다 — 아주 작은 값은 보통 반올림 노이즈이고, 아주 큰 값은 종종 서로 다른 두 토큰이 이름을 공유한다는 의미입니다. |
| 0.25 | 동일한 토큰 경로가 두 소스 모두에 존재합니다. |
| 0.15 | 두 소스가 토큰의 |
점수는 의도적으로 약 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 testApache-2.0. 사용하고, 포크하고, 이를 기반으로 제품을 만드세요.
wildchild.ai가 제작했습니다.
This server cannot be deployed
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Primary-source SEC filing intelligence and financial/disclosure reconciliation for AI agents.
52 paid x402 API endpoints for AI agents — crypto, data, DeFi, market intelligence.
Give your AI agents the tools to build, manage, and run automation workflows.
