Ihr Designsystem sagt das eine, Ihr Produkt liefert das andere. Dieses Tool zeigt Ihnen genau, wo.

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

Geben Sie ihm zwei beliebige Quellen – einen Design-Tool-Export (Figma, Sketch, Penpot, Tokens Studio …), eine Live-Website- oder Web-App-URL, eine Codebase-Token-Datei – und es erstellt einen echten Drift-Bericht. Website-URLs werden live gescannt (die Extraktion wird an den Open-Source-Dembrandt-Extractor delegiert), es gibt also nichts einzurichten und nichts ist inszeniert: Der Bericht ist Ihr tatsächliches Designsystem, so wie es gerade existiert.

Keine Argumente? npx token-reconciler öffnet eine geführte Startseite, die Sie durch den Prozess führt.

Das Problem

Ein Designsystem lebt nie an einem Ort. Es gibt die Figma-Datei, das ausgelieferte CSS und die Codebase – drei Kopien derselben Entscheidungen. Mit der Zeit weichen sie still voneinander ab: Ein Entwickler codiert Tailwinds Blau statt des Marken-Indigo, Figma bekommt ein neues Grau, das nie ausgeliefert wird, eine Überschrift geht auf 700, wo die Typografie-Skala 600 sagt. Kein einzelnes Tool bemerkt das, weil jedes Tool nur seine eigene Kopie sieht.

Bis 2026 ist die Extraktions-Seite dieses Problems gelöst – gute Open-Source-Tools ziehen Tokens aus Live-Websites, und Figma exportiert Variablen – alle sprechen dasselbe DTCG-Format (der W3C-Design-Tokens-Community-Group-Standard: eine vereinbarte JSON-Struktur für Design-Tokens, sodass jedes Tool die Ausgabe jedes anderen Tools lesen kann). Was fehlte, ist der Schritt danach: diese Dateien zu vergleichen und zu wissen, welche Unterschiede wichtig sind. Genau das macht dieses Tool.

Related MCP server: Figma Console MCP Server

Was Sie bekommen

Die Ausführung eines Vergleichs erzeugt einen Bericht mit drei Abschnitten:

• Konflikte – dasselbe Token, in zwei Quellen unterschiedlich definiert, sortiert nach einem 0–1-Konfidenz-Score dafür, wie sehr der Unterschied zählt. Die Bewertung ist typbewusst: Farben werden wahrnehmungsbasiert (OKLab) verglichen, nicht als Strings – so ist #FFFFFF vs. rgb(255,255,255) kein Konflikt, während zwei Grautöne, die einen Farbton auseinanderliegen, sehr wohl einer sind. Dimensionen und Dauern werden einheitennormalisiert (1rem = 16px, 0.3s = 300ms), und DTCG-Aliase werden vor dem Vergleich aufgelöst, sodass {color.base.indigo.500} vs. sein Rohwert übereinstimmen.

• Nicht zugeordnete Tokens – entworfen, aber nie ausgeliefert, oder ausgeliefert, aber nie entworfen. Noch keine Konflikte; meistens der Ursprung des nächsten.

• Ein vorgeschlagener Lösungsansatz pro Konflikt – von einem bewusst einfachen Standard-Resolver (mostRecentWins), mit seiner Begründung. Klügere Auflösung ist pluggable.

• Barrierefreiheitsanalyse, aktueller und nächster Standard – Text-Rollen-Farbtokens werden mit Hintergrund-Rollen-Tokens gepaart und gegen WCAG 2.2 AA (4.5:1 – der aktuelle W3C-Standard, und die Stufe, an die EU-EAA-/ADA-Regeln binden) geprüft, mit AAA und einer informativen APCA-Messung (der WCAG-3.0-Entwurfsalgorithmus) pro Paar. Das Besondere: Da dieses Tool mehrere Quellen sieht, kann es sagen, wann Drift die Barrierefreiheit verändert hat – dasselbe Paar besteht AA in Figma, scheitert aber auf der ausgelieferten Website. Ein generisches Audit kann das nicht sagen; ein Reconciler schon.

Hier ein Ausschnitt aus einem echten Lauf (zwei Produktions-Websites, live gescannt):

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

So verwenden Sie es

Vergleichen Sie Ihr Designsystem mit Ihrem Produkt (das Hauptfeature):

1. Exportieren Sie die Tokens Ihres Designsystems als DTCG-JSON aus dem jeweiligen Tool – Figma (Community-Plugins wie „Design Tokens (W3C)“ oder DesignBridge), Penpot (nativer DTCG-Export), Sketch oder Tokens Studio.

2. Führen Sie aus:

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

Beliebige zwei Quellen vergleichen – jedes Argument kann ein .json-Dateipfad, eine URL zu einer Token-Datei oder eine zu scannende Website-URL sein:

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

Geführter Modus – wenn Sie nicht sicher sind, wo Sie anfangen sollen:

npx token-reconciler

In CI – der Exit-Code ist das Drift-Gate (0 sauber, 1 hochvertrauenswürdige Konflikte, 2 Eingabefehler):

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

Nützliche Flags: --json (JSON-Bericht), --out <datei>, --names a,b, --kinds figma-variables,live-site, --threshold <0..1>, --no-fail. Siehe examples/ci-usage.md für ein vollständiges GitHub-Actions-Setup und examples/dembrandt-vs-figma.md für eine ausführliche Anleitung.

Über Marketing-Websites hinaus: SaaS, Web-Apps und mobile Apps

Designsysteme leben hauptsächlich in Produkten, nicht in öffentlichen Websites. Jede Art von Produkt lässt sich anbinden – die Quelle unterscheidet sich nur:

Eingeloggte SaaS-/Web-Apps. Sie sind immer noch Web – der Scanner braucht nur Ihre Session. Holen Sie sich Ihr Cookie aus den DevTools des Browsers (Application → Cookies) und reichen Sie es durch:

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

--header "Authorization: Bearer …" funktioniert auch für token-authentifizierte Apps. Scannen Sie die relevanten Screens, indem Sie direkt auf ihre URLs zeigen.

Mobile Apps (iOS / Android / React Native / Flutter). Es gibt keine URL zum Scannen – aber die Design-Tokens einer mobilen App leben in ihrer Codebase, was sogar besser ist als Scannen: Android-Compose-/XML-Themes, iOS-Asset-Kataloge, React-Native-Theme-Dateien. Wenn Sie Style Dictionary oder Tokens Studio verwenden, ist Ihr Quell-Token-JSON bereits DTCG-kompatibel – speisen Sie es direkt ein:

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

Dieser Codebase-als-Quelle-Pfad ist auch für Web-Apps der präziseste, wenn Sie eher beabsichtigte Code-Tokens als gescannte berechnete Stile vergleichen möchten.

Alle drei gleichzeitig. Das Tool akzeptiert 2+ Quellen – so kann ein Lauf die Frage beantworten: „Stimmen Figma, die Web-App und das Mobile-Theme überein?“

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

Nutzung über einen KI-Agenten (MCP)

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

Drei Tools: reconcile(sources) führt einen Vergleich durch und liefert den bewerteten Bericht; get_conflicts(runId) ruft einen vergangenen Lauf ab; explain_conflict(runId, tokenPath) zerlegt einen Konflikt vollständig – Roh- und aufgelöste Werte pro Quelle, Alias-Ketten und jeden Konfidenzfaktor mit Gewichtung und Begründung. Passt natürlich zu Extractor-MCP-Servern: Ein Agent kann eine Website mit Dembrandt scannen und in einer Konversation mit einem Figma-Export abgleichen.

Nutzung als Bibliothek

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 akzeptiert einen Dateipfad, eine http(s)-URL oder ein bereits geparstes DTCG-Objekt. Wenn eine Quelle einen Extraktionszeitstempel in $extensions trägt (Dembrandt tut das), wird er automatisch übernommen.

So funktioniert die Konfidenzbewertung

Der Score jedes Konflikts setzt sich aus drei dokumentierten Faktoren zusammen – die vollständige Aufschlüsselung wird in jedem Bericht mitgeliefert, nie eine Blackbox:

Der Score ist bewusst auf etwa 0,97 gedeckelt: Es ist eine Heuristik, und eine Heuristik, die 1,00 behauptet, würde lügen.

Eigene Resolver einbinden

Das Erkennen von Konflikten ist die Aufgabe dieser Bibliothek; den Gewinner zu entscheiden ist pluggable. Ein bewusst einfacher Resolver ist enthalten (mostRecentWins – neueste Extraktion gewinnt; ohne Zeitstempel enthält er sich). Einen eigenen zu schreiben ist eine Funktion:

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

Jede Auflösung trägt immer eine reasoning-Zeichenkette. Herkunft ist der Punkt.

Umfang – was dieses Tool bewusst nicht tut

• Keine eigene Extraktions-Engine. Website-Scannen wird an Dembrandt delegiert; Figma-Export gehört zu Figma-Plugins. Dieses Tool beginnt dort, wo Extractor aufhören.

• Kein erfundenes Schema. Standard-DTCG rein, Standard-DTCG-Konzepte raus.

• Keine vorgetäuschte Urteilskraft. Der Standard-Resolver ist ehrlich darin, dumm zu sein. Echtes Urteilsvermögen – die Absicht Ihres Systems zu kennen – ist ein anderes Produkt.

Funktioniert hervorragend mit

• Dembrandt – Live-Website → DTCG-Tokens; treibt die URL-Scan-Funktion dieses Tools.

• designlang – Live-Website → Tokens + Layout + A11y-Daten (GitHub).

• uiscanner – URL → Token-Zerlegung über MCP.

• DesignBridge – Figma-Designsystem → strukturierte DESIGN.md + Tokens.

• W3C-DTCG-Format – das Austauschformat, das all das komponierbar macht.

Entwicklung

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

Lizenz

Apache-2.0. Nutzen Sie es, forken Sie es, bauen Sie Produkte darauf.

Erstellt von wildchild.ai