Ваша дизайн-система говорит одно. Продукт выпускает другое. Этот инструмент покажет, где именно.

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

Передайте ему любые два источника — экспорт из дизайн-инструмента (Figma, Sketch, Penpot, Tokens Studio…), URL живого сайта или веб-приложения, файл токенов из кодовой базы — и он выведет настоящий отчёт о расхождениях. URL сайтов сканируются вживую (извлечение делегируется опенсорсному экстрактору Dembrandt), так что настраивать нечего и ничего не подготавливается: отчёт — это ваша реальная дизайн-система в её текущем виде.

Без аргументов? npx token-reconciler запускает интерактивный мастер, который проведёт вас по шагам.

Проблема

Дизайн-система никогда не живёт в одном месте. Есть файл Figma, опубликованный CSS и кодовая база — три копии одних и тех же решений. Со временем они тихо перестают совпадать: разработчик захардкодил синий из Tailwind вместо фирменного индиго, в Figma появился новый серый, который никогда не попадает в продукт, заголовок выходит за 700, хотя типографическая шкала говорит 600. Ни один инструмент этого не замечает, потому что каждый видит только свою копию.

К 2026 году сторона извлечения уже решена — хорошие опенсорсные инструменты вытаскивают токены с живых сайтов, а Figma экспортирует Variables — и все они говорят на одном формате DTCG (стандарте W3C Design Tokens Community Group: единая согласованная JSON-структура для дизайн-токенов, благодаря которой каждый инструмент может читать вывод любого другого). Чего не хватало — следующего шага: сравнивать эти файлы и понимать, какие различия важны. Именно это и делает инструмент.

Related MCP server: Figma Console MCP Server

Что вы получаете

Запуск сравнения формирует отчёт из трёх разделов:

• Конфликты — один и тот же токен определён по-разному в двух источниках, отсортированы по оценке уверенности от 0 до 1, отражающей, насколько различие существенно. Оценка учитывает тип: цвета сравниваются перцептуально (OKLab), а не как строки — поэтому #FFFFFF против rgb(255,255,255) — это не конфликт, а два серых, различающихся на один оттенок, — конфликт. Размеры и длительности нормализуются по единицам (1rem = 16px, 0.3s = 300ms), а алиасы DTCG разрешаются перед сравнением, так что {color.base.indigo.500} и его сырое значение согласуются.

• Несопоставленные токены — спроектированы, но не попали в продукт, либо попали, но не были спроектированы. Пока не конфликты; обычно именно здесь зреет следующий.

• Предлагаемое разрешение каждого конфликта — от намеренно простого резолвера по умолчанию (mostRecentWins) с указанием обоснования. Более умное разрешение подключается.

• Анализ доступности: текущий и следующий стандарт — цветовые токены с ролью текста сопоставляются с токенами с ролью фона и проверяются на WCAG 2.2 AA (4.5:1 — текущий стандарт W3C, тот уровень, к которому привязываются требования EU EAA / ADA), плюс по каждой паре даётся уровень AAA и информативный показатель APCA (черновой алгоритм WCAG 3.0). Уникальность в том, что этот инструмент видит несколько источников и может сказать, когда расхождение изменило доступность — одна и та же пара проходит AA в Figma, но не проходит на опубликованном сайте. Обычный аудит такого не скажет, а сверщик — может.

Вот фрагмент реального запуска (два продакшен-сайта, отсканированы вживую):

### 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 и веб-приложения с входом. Это по-прежнему веб — сканеру просто нужна ваша сессия. Возьмите cookie из инструментов разработчика браузера (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 принимает путь к файлу, URL http(s) или уже разобранный 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 — живой сайт → токены + layout + данные a11y (GitHub).

• uiscanner — URL → разбор токенов через MCP.

• DesignBridge — дизайн-система Figma → структурированные DESIGN.md + токены.

• W3C DTCG format — формат обмена, который делает всё это компонуемым.

Разработка

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

Лицензия

Apache-2.0. Используйте, форкайте, стройте на нём продукты.

Разработано wildchild.ai