D
DesignLatch Design Compliance Toolkit
Design Compliance Toolkit

Keep your UI honest.

DesignLatch catches the gap between your design tokens and your live UI — automatically. It compares expected token values against actual computed styles, then surfaces every drift as a scored compliance report.

Quick Start

Two adapters, one engine

Use the CLI for terminal-based workflows with Playwright and HTML reports. Use MCP when an AI agent already holds your data inline and needs JSON-only results.

CLI@designlatch/cli
MCP@designlatch/mcp
CLI outputsJSON + HTML
MCP toolsvalidate + scan

Full docs →

CLI commands with every flag explained, MCP tool reference, inputs, outputs, and architecture — all in one place.

Problem 😬

Design tokens drift silently

Your Figma spec says --color-primary: #2dd4a0. Your live site? Nobody checked. A hardcoded hex slipped in. Three sprints later, half your buttons are the wrong shade and nobody noticed until a stakeholder screenshot landed in Slack.

Solution ✅

Automated, scored compliance

DesignLatch compares your token definitions against computed CSS captured from a real browser, rule by rule, and gives you a score. Run it in CI to catch drift before it ships.

$_
CLI

@designlatch/cli

Terminal workflow. Collects snapshots via Playwright, generates HTML reports, and works entirely with files on disk.

{}
MCP

@designlatch/mcp

AI agent workflow. Accepts inline JSON over stdio, returns structured results, and works best when the agent can also reach Playwright MCP and Figma MCP.

Quick Start

CLI + MCP
1

Define expectations

Write a .designlatch.json config listing selectors, rules, and expected token values - your compliance spec.

2

Capture reality

The CLI uses Playwright to open your live site and record every computed CSS value. MCP receives snapshots as inline JSON from the agent workflow.

3

Compare and report

The engine diffs expected vs actual, scores compliance, and returns an HTML report (CLI) or structured JSON summary (MCP).

CLI - Install
bash
npm install -D @designlatch/cli
npx designlatch init
CLI - Full scan
bash
npx designlatch collect --config .designlatch.json --url https://app.example.com --out snapshots.json
npx designlatch scan --tokens tokens.json --snapshots snapshots.json --report-dir report
MCP - Connect
bash
  claude mcp add --transport stdio designlatch npx -- -y @designlatch/mcp
MCP - Agent prompt
text
Use Playwright MCP and Figma MCP to gather the live selector styles and the matching design values.
Then call DesignLatch MCP compare_live_ui_to_figma and return the score, mismatches, and report path.
Docs - v1

DesignLatch docs

DesignLatch keeps your live UI honest against your design system. It compares expected token values with actual computed styles and gives you a scored compliance report - through a terminal CLI or an AI-agent MCP server.

$_
CLI

@designlatch/cli

Terminal workflow - Playwright collection, file-based inputs, offline HTML reports. Great for CI and local dev.

{}
MCP

@designlatch/mcp

AI agent workflow - accepts inline JSON over stdio, returns structured results, and fits best when the agent can also reach Playwright MCP and Figma MCP.

Why it exists

The problem and the solution

Design drift is invisible until it's embarrassing. Here's what DesignLatch fixes.

Problem😬

Tokens drift silently

Your Figma says --color-primary: #2dd4a0. Your live site? Nobody checked. A hardcoded hex slipped in. Three sprints later, half your buttons are the wrong shade.

Manual visual QA is slow, inconsistent, and doesn't scale.

Solution✅

Automated compliance

DesignLatch captures computed CSS from a real browser, diffs it against your token spec rule-by-rule, and returns a scored report.

Run it in CI to fail builds on drift. Objective, repeatable compliance.

Concept

How it works in 3 steps

The same core engine runs under both adapters.

1

Define expectations

Write a .designlatch.json config listing selectors, rules, and expected token values - your compliance spec.

2

Capture reality

CLI uses Playwright to open your live site and record computed CSS. MCP receives snapshots as inline JSON from the agent.

3

Compare and report

The engine diffs expected vs actual, scores compliance, and returns an HTML report (CLI) or structured JSON (MCP).

*

New to this? Start with the CLI. Install it, run npx designlatch init, then follow the commands below step by step.

Architecture

Package layout

Three packages, one engine. Both adapters share the same core.

Core

@designlatch/core

Pure engine - validation logic, token resolution, style comparison, scoring, report utilities. No I/O.

App

@designlatch/app

Shared workflows: validateInputs() and scanCompliance(). Both adapters call these.

Adapters

CLI + MCP

Sibling packages. CLI adds Playwright + HTML. MCP adds a stdio JSON interface for AI agents.

Status

What's shipped in v1

CLI is live with all five commands: init, collect, validate, scan, and serve.
MCP v1 is live as a stdio server with three tools.
MCP exposes three tools: compare_live_ui_to_figma, validate_inputs, and scan_compliance.
Playwright collection & HTML reports are CLI-only - not part of the MCP surface in v1.
MCP accepts inline JSON and returns JSON-first results. The compare flow still depends on agent access to Playwright MCP and Figma MCP.
CLI Adapter
CLI

CLI adapter - file-based workflow

@designlatch/cli

The CLI is the right choice when you want to run compliance checks locally, collect real snapshots from a live site, and generate readable HTML reports.

Install

Get started

bash
npm install -D @designlatch/cli
npx designlatch help
How to use

Recommended CLI flow

init-> Scaffold project files
collect-> Capture live computed styles
validate-> Check inputs are well-formed
scan-> Run the compliance engine
serve-> Open the HTML report
*

How to use the CLI: initialize your workspace, keep tokens/config on disk, collect snapshots from a live site, validate inputs, scan for compliance, then serve the HTML report for review.

init

Bootstrap the workspace

Use init first when starting a new DesignLatch project. It scaffolds the baseline config plus the local designlatch/ folder structure so the rest of the CLI flow has predictable inputs.

bash
npm install -D @designlatch/cli
npx designlatch init
collect

Capture live computed styles

Run collect when you want DesignLatch to open the real product in Playwright and write fresh snapshots to disk. This is the moment where the CLI turns your running UI into measurable input data.

bash
npx designlatch collect --config .designlatch.json --url https://app.example.com --out designlatch/snapshots.json
validate

Check config, tokens, and snapshots before scanning

Use validate as a fast sanity check. It verifies that the config is readable, the token map resolves, and the snapshots are shaped correctly before you spend time debugging scan output.

bash
npx designlatch validate --config .designlatch.json --tokens designlatch/tokens.json --snapshots designlatch/snapshots.json
scan

Run the compliance engine and generate reports

Use scan for the actual comparison pass. It takes the expected tokens, the observed snapshots, and the config rules, then produces scored JSON and HTML output your team can review or gate in CI.

bash
npx designlatch scan --config .designlatch.json --tokens designlatch/tokens.json --snapshots designlatch/snapshots.json --report-dir report
serve

Review the HTML report locally

Use serve after scan when you want to inspect the generated report in the browser, share it locally, or quickly verify what actually failed without parsing raw JSON.

bash
npx designlatch serve --report-dir report
MCP Adapter
MCP

MCP adapter - agent workflow over stdio

@designlatch/mcp

The MCP adapter is the right choice when an AI agent already has design data and live UI data in memory, or when you want the agent to orchestrate a comparison flow and return a structured summary instead of a manual terminal workflow.

Install

Connect the MCP server

bash
  
                    claude mcp add --transport stdio designlatch npx -- -y @designlatch/mcp
3 tools

Current MCP surface

compare_live_ui_to_figma-> High-level agent workflow
validate_inputs-> Verify raw payload shape
scan_compliance-> Run the comparison engine
{}

How to use MCP: configure DesignLatch in an MCP-capable AI client, make sure Playwright MCP and Figma MCP are also available for the compare flow, let the agent gather live and design data, then call the DesignLatch tools to validate and scan.

How to use

Recommended MCP flow for agentic AI

1

Connect DesignLatch

Add the MCP server to your AI client and restart the agent session so the tools become visible.

2

Gather design + live data

Use Playwright MCP for computed styles and Figma MCP for the matching component or token values.

3

Compare and summarize

Call compare_live_ui_to_figma for the high-level flow, or use validate_inputs and scan_compliance directly when you already have raw JSON.

compare_live_ui_to_figma

Preferred high-level MCP workflow

This tool is the agent-facing entrypoint when the task sounds like a natural comparison request. It checks prerequisites first, tells the agent what is missing, and once the live/Figma data is supplied it synthesizes the DesignLatch payloads internally and runs the scan.

Response states
blocked means Playwright MCP, Figma MCP, or Figma auth is missing. validated means the prerequisites are available but the agent still needs to gather liveCapture or figmaDesign. completed returns score, mismatches, and report paths. failed means validation or scan execution broke.
Prompt

Sample prompt - high-level compare flow

text
Compare live site (google.com's) search bar UI with this Figma search bar component (Figma Link) using designlatch mcp.
Payload

Sample input shape

json
{
  "request": "Compare google.com's search bar UI with this Figma search bar component",
  "liveUrl": "https://google.com",
  "selector": "textarea[name='q']",
  "figmaFileOrUrl": "https://www.figma.com/file/abc123/search-bar",
  "figmaNodeIdOrComponentName": "Search Bar",
  "prerequisites": {
    "playwrightMcpConfigured": true,
    "figmaMcpConfigured": true,
    "figmaAuthenticated": true
  }
}
validate_inputs

Use when you already have raw DesignLatch JSON

Call validate_inputs when the agent has already assembled config, tokens, and optionally snapshots, and you want a fast structure check before a full compliance scan.

text
Validate these DesignLatch inputs first. If they pass, I will run scan_compliance next.
Return the validation result and tell me if any token references or snapshot shapes are wrong.
scan_compliance

Run the engine directly from inline JSON

Call scan_compliance when the agent already has the final payloads and wants the report immediately. This is the most direct path when Playwright/Figma orchestration happens outside DesignLatch.

text
Run DesignLatch scan_compliance with the validated config, tokens, and snapshots.
Return the pass/fail result, score, top mismatches, and report output paths.
Reference

Inputs

CLI inputs

The CLI works with files on disk: a DesignLatch config, a token map, and captured snapshots. The workflow is explicit and repeatable, which makes it a strong fit for local development and CI.

MCP inputs

The MCP tools work with inline JSON. In the high-level compare flow, the agent first gathers live and design data, then passes normalized payloads or prerequisite status into DesignLatch.

Reference

Outputs

CLI outputs

The CLI writes snapshots during collection and generates a JSON report plus an HTML report during scanning. That makes it ideal when a human still wants to inspect the final report visually.

MCP outputs

The MCP tools return structured results to the agent. The compare flow also returns report paths so the agent can summarize the scan and point the user to the generated artifacts.