@uimatch/cli

CLI tool for comparing Figma designs with implementation. Provides visual comparison and quality scoring.

Features

• Figma Integration: Direct integration with Figma API and MCP server
• Quality Scoring: Design Fidelity Score (DFS) with configurable thresholds
• Quality Gate Profiles: Pixel-perfect, development, or lenient comparison modes
• Extensible: Plugin architecture for custom selector resolution

Installation

# Global installation (recommended)
npm install -g @uimatch/cli playwright
npx playwright install chromium

# Or project-local installation
npm install -D @uimatch/cli playwright
npx playwright install chromium

Quick Start

Basic Comparison

npx uimatch compare \
  figma=AbCdEf123:456-789 \
  story=http://localhost:6006/?path=/story/button \
  selector="#root button"

With Quality Profile

npx uimatch compare \
  figma=AbCdEf123:456-789 \
  story=http://localhost:6006 \
  selector=".card" \
  profile=component/strict

With Output Directory

npx uimatch compare \
  figma=AbCdEf123:456-789 \
  story=http://localhost:6006 \
  selector=".card" \
  outDir=./comparison-results

Commands

compare

Compare a single Figma design with implementation.

Parameters:

• figma: Figma file key and node ID (format: fileKey:nodeId)
• story: Implementation URL (Storybook, localhost, or deployed)
• selector: CSS selector for target element
• profile: (Optional) Quality profile - component/strict | component/dev | page-vs-component | lenient | custom
• outDir: (Optional) Output directory for artifacts (screenshots, diffs)

suite

Run multiple comparisons from a JSON configuration file.

npx uimatch suite path=suite-config.json

doctor

Diagnose installation and configuration issues.

npx uimatch doctor

text-diff

Compare two text strings and show similarity score with classification.

npx uimatch text-diff <expected> <actual> [options]

Options:

• --case-sensitive: Perform case-sensitive comparison (default: case-insensitive)
• --threshold=<number>: Similarity threshold (0-1, default: 0.9)

Output:

Returns a JSON object with:

• kind: Classification (exact-match | whitespace-or-case-only | normalized-match | mismatch)
• similarity: Similarity score (0-1)
• normalizedExpected / normalizedActual: Normalized text values

Example:

npx uimatch text-diff "Sign in" "SIGN  IN"
# → kind: 'whitespace-or-case-only', similarity: 1.0

npx uimatch text-diff "Submit" "submit" --case-sensitive
# → kind: 'whitespace-or-case-only', similarity: 1.0

npx uimatch text-diff "Hello" "Helo" --threshold=0.6
# → kind: 'normalized-match', similarity: 0.8

For details, see CLI Reference → Text Comparison.

Programmatic API

import { uiMatchCompare } from '@uimatch/cli';

const result = await uiMatchCompare({
  figma: 'AbCdEf123:456-789',
  story: 'http://localhost:6006',
  selector: '#button',
  profile: 'component/strict',
});

console.log(`DFS: ${result.dfs}`);
console.log(`Status: ${result.status}`);

Configuration

Create .uimatchrc.json in your project root:

{
  "comparison": {
    "acceptancePixelDiffRatio": 0.01,
    "acceptanceColorDeltaE": 3.0
  }
}

Quality Gate Profiles

Profile	pixelDiffRatio	ΔE	Use Case
component/strict	0.01 (1%)	3.0	DS component validation
component/dev	0.08 (8%)	5.0	Dev iteration
page-vs-component	0.12 (12%)	5.0	Padded page comparison
lenient	0.15 (15%)	8.0	PoC/prototype
custom	(from config)	-	From settings file

Environment Variables

FIGMA_ACCESS_TOKEN=your_token_here       # Required for Figma API
UIMATCH_HEADLESS=true|false              # Browser headless mode (default: true)
UIMATCH_LOG_LEVEL=info|debug|silent      # Logging verbosity (default: info)

Documentation

For complete documentation, see the uiMatch Documentation Site:

• Getting Started - Installation and quickstart
• CLI Reference - Complete command reference and options
• Concepts - Quality gates, scoring layers, and workflows
• Troubleshooting - Common issues
• Plugins - Custom selector plugins
• API Reference - TypeScript API documentation

License

MIT