@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/cli compare \
  figma=AbCdEf123:456-789 \
  story=http://localhost:6006/?path=/story/button \
  selector="#root button"

With Quality Profile

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

With Output Directory

npx @uimatch/cli 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 | page/text-doc | lenient | custom
• areaGapCritical: (Optional) Area gap threshold for immediate failure (0-1, default: 0.15)
• areaGapWarning: (Optional) Area gap threshold for warning (0-1, default: 0.05)
• outDir: (Optional) Output directory for artifacts (screenshots, diffs)

suite

Run multiple comparisons from a JSON configuration file.

npx @uimatch/cli suite path=suite-config.json

doctor

Diagnose installation and configuration issues.

npx @uimatch/cli doctor

version

Display the current version of the CLI.

npx @uimatch/cli version
# or
npx @uimatch/cli --version
# or
npx @uimatch/cli -v

text-diff

Compare two text strings and show similarity score with classification.

npx @uimatch/cli 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/cli text-diff "Sign in" "SIGN  IN"
# → kind: 'whitespace-or-case-only', similarity: 1.0

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

npx @uimatch/cli 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 | | page/text-doc | 0.20 (20%) | 6.0 | Text-heavy pages | | 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