Tu sistema de diseño dice una cosa. Tu producto entrega otra. Esto te muestra exactamente dónde.

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

Dale dos fuentes cualesquiera — una exportación de herramienta de diseño (Figma, Sketch, Penpot, Tokens Studio…), una URL de sitio en vivo o de aplicación web, un archivo de tokens de la base de código — y genera un informe de deriva real. Las URLs de sitios se escanean en vivo (la extracción se delega en el extractor de código abierto Dembrandt), así que no hay nada que configurar ni nada preparado: el informe es tu sistema de diseño real, tal y como existe ahora mismo.

¿Sin argumentos? npx token-reconciler abre un inicio guiado que te acompaña paso a paso.

El problema

Un sistema de diseño nunca vive en un solo lugar. Está el archivo de Figma, el CSS publicado y la base de código — tres copias de las mismas decisiones. Con el tiempo dejan de estar de acuerdo silenciosamente: un desarrollador fija el azul de Tailwind en el código en lugar del índigo de la marca, a Figma le llega un gris nuevo que nunca se publica, un encabezado sale en 700 cuando la escala tipográfica dice 600. Ninguna herramienta lo detecta, porque cada herramienta solo ve su propia copia.

De cara a 2026, la parte de la extraer está resuelta: buenas herramientas de código abierto extraen tokens de sitios en vivo, y Figma exporta Variables — y todas hablan el mismo formato DTCG (el estándar del W3C Design Tokens Community Group: una forma de JSON acordad para los tokens de diseño, de modo que cada herramienta pueda leer la salida de cualquier otra). Lo que faltaba es el paso posterior: comparar esos archivos y saber qué diferencias importan. Eso es lo que hace esta herramienta.

Related MCP server: Figma MCP Server by Bao To

Qué obtienes

Al ejecutar una comparación se produce un informe con tres secciones:

• Conflictos — el mismo token definido de manera distinta en dos fuentes, ordenado por una puntuación de confianza de 0 a 1 para saber cuánto importa la diferencia. La puntuación es tipa por tipo: los colores se comparan de forma perceptiva (OKLab), no como cadenas — así que #FFFFFF vs rgb(255,255,255) no es un conflicto, mientras que dos cualquier grises un tono de ritmo sí lo es. Las dimensiones y duraciones se normalizan por unidades (1rem = 16px, 0.3s = 300ms), y los alias DTCG se resuelven antes de comparar, por lo que {color.base.indigo.500} está de acuerdo con su valor literal.

• Tokens sin coincidencia — diseñados pero nunca publicador, o publicados pero nunca diseñados. No son conflictos aún; suele haber ser el origen del siguiente conflicto.

• Una resolución sugerida por conflicto — desde a resolver a propósito simple (mostRecentWins), con el razonamiento explicado. El resolver más inteligente puede enchufarse.

• Análisis de accesibilidad, actual y para el próximo estándar — los tokens de color de texto se emparejan con los de fondo y se comparan con WCAG 2.2 AA (4.5:1 — el estándar actual de la W3C, y el nivel al que se atienen las reglas de la UE EAA / ADA), con una lectura de AAA y una APCA informativa (el algoritmo de WCAG 3.0 en su estado de borrador) por pareja. La parte única: porque esta herramienta ve múchas fuentes, puede decirte cuándo la deriva cambió la accesibilidad: el mismo emparejamiento pasa AA puedes comparar con AA en Figma, pero falla en el sitio publicado. Una auditoría sencilla no puede decir eso; un reconciliador sí.

Aquí tienes un fragmento de una ejecución real (dos sitios en producción, escaneados en directo):

### 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 |

Cómo usarlo

Compara tu sistema de diseño con tu producto (el evento):

1. Exporta los tokens de tu sistema de diseño a DTCG JSON desde la herramienta que lo tenga — Figma (plugins de la comunidad como «Design Token (W3C)» o DesignBridge), Penpot (exportación DTCG nativa), Sketch o Tokens Studio.

2. Ejecuta:

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

Comprueba dos fuentes cualesquiera — cualquier argumento puede ser una ruta a un archivo .json, una URL de un archivo de tokens o una URL de un sitio para escanear:

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

Modo guiado — si no sabes por dónde empezar:

npx token-reconciler

En CI — el código de salida es la puerta de deriva (0 limpio, 1 conflictos de alta confianza, 2 error de entrada):

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

Opciones útiles: --json (informe JSON), --out <archivo>, --names a,b, --kinds figma-variables,live-site, --threshold <0..1>, --no-fail. Consulta examples/ci-usage.md para una configuración completa de GitHub Actions y examples/dembrandt-vs-figma.md para un tutorial completo.

Much más que sitios de marketing: SaaS, aplicaciones web y móviles

Los sistemas de desarrollo viven mayoremente en los productos, no en los sitios de marketing web públicos. Todos los productos conectan: la fuente solo cambia:

SaaS / aplicaciones web con sesión. Siguen siendo web, por lo que el escáner necesariamente necesita tu sesión. Puedes tomar la cookie de las herramientas de desarrollador del navegador (Application → Cookies) y pasarla por línea de comandos:

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

--header "Authorization: Bearer …" también funciona para apps autenticadas por token. Escanea las pantallas importantes apuntando directamente a sus URLs.

Apps móviles (iOS / Android / React Native / Flutter). No hay URL que escanear, pero los tokens de diseño de una app móvil viven en su código fuente, que es aún mejor que escannear: temas de Android Compose/XML, asset catalogs de iOS o archivos de tema de React Native. Si usas Style Dictionary o Tokens Studio, tu token JSON ya es compatible con DTCG — pásalo directamente:

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

Esta ruta de código fuente como fuente también es la más precisa para las aplicaciones web, si prefieres comparar intencionados tokens de código (medida que establece intencionado no) y en lugar de estilos nativos.

Los seis y tres al mismo tiempo. La herramienta acepta 2+ fuentes, por lo que una sola ejecución puede responder: ¿Figma, la aplicación web y el tema móvil coinciden?

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

Úsalo desde un agente de IA (MCP)

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

Tres herramientas: reconcile(sources) ejecuta una comparación y devuelve el informe puntuado; get_conflicts(runId) recupera una ejecución anterior; explain_conflict(runId, tokenPath) desglosa por completo un conflicto — valores crudos y resuelto por fuente, cadenas de alias, y cada factor de confianza con su peso y razonamiento. Combina naturalmente con los servidores MCP de extracción: un agente puede escanear un sitio con Dembrandt y reconciliar con una exportación de Figma en una sola conversación.

Úsalo como librería

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 acepta una ruta de archivo, una URL http(s) o un objeto DTCG ya analizado. Si una fuente contiene una marca de extracción en $extensions (Dembrandt la incluye), se detecta automáticamente.

Cómo funciona la puntuación de confianza

El puntaje de cada conflicto se construye a partir de tres factores documentados — el desglose completo se incluye en cada informe, nunca es una caja negra:

La puntuación llega a 0,97 de manera deliberada: es una heurística, y una heurística que dijera 1,00 estaría teniendo.

Conectando tu propio resolver

Detectar conflictos es el trabajo de esta librería; decidir quién gana es conectable. Se aporta un resolver deliberadamente simple (mostRecentWins — el más reciente ganador; se abstiene si se reduce marcas de tiempo). Escribir la suya es una sola función:

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",
  };
};

Cada resolución lleva una cadena de reasoning, siempre. La proveniencia es el objetivo.

Alcance — lo que se no hace deliberadamente

• Ningún motor de extracción propio. El escaneo de sitios se ha delegado en Dembrandt; Exportación de Figma pertenece a los plugins de Figma. Esta herramienta comienza donde se detienen los extractores.

• Sin esquema inventado. DTCG estándar al in... DTCG estándar al out.

• Sin juicio fingido. El resolver predeterminado es honesto al ser tonto. El juicio real — saber la intención de tu sistema — es otra por completo.

Funciona muy bien con

• Dembrandt — sitios en vivo → tokens DTCG;: impulsa el escaneo de URL de esta herramienta.

• designlang — identidad en vivo → tokens + layout + datos de audio (GitHub).

• uiscanner — URL → desglose de tokens vía MCP.

• DesignBridge: avala sistema de diseño de Figma → estructura clara DESIGN.md + tokens.

• Formato DTCG de la W3C — el formato de intercambio que hace que todo esto sea combinación.

Desarrollo

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

Licencia

Apache-2.0. Úsalo, has un fork y crea productos sobre él.

Creado por wildchild.ai