Skip to main content

@uimatch/cli

Command-line and programmatic entry point for comparing Figma designs with implemented interfaces. Its reports are machine-readable, so they fit into CI checks, review workflows, and experimental AI-assisted repair loops.

Installation​

Install the CLI with Playwright, then install Chromium:

npm install -D @uimatch/cli playwright
npx playwright install chromium

Set FIGMA_ACCESS_TOKEN when using the Figma API:

export FIGMA_ACCESS_TOKEN="figd_..."

Quick start​

npx @uimatch/cli compare \
  figma=AbCdEf123:456-789 \
  story=http://localhost:6006/iframe.html?id=button--primary \
  selector="#storybook-root button" \
  profile=component/strict \
  outDir=./comparison-results

Commands​

CommandPurpose
compareCompare one Figma node with one implementation
suiteRun comparisons defined in a JSON suite
text-diffCompare two strings after uiMatch text normalization
doctorDiagnose the runtime, browser, and anchors setup
settingsInspect or reset the effective project configuration
versionPrint the CLI version

The CLI Reference defines command arguments, configuration keys, environment variables, output, and exit codes.

Programmatic use​

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

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

console.log(result.report.metrics.dfs);
console.log(result.summary);

Programmatic callers receive a result object and remain responsible for their own process exit behavior.

Each call starts and closes its own browser. Pass reuseBrowser: true to share one across calls, then call closeUiMatchBrowsers() once they have all settled — the shared browser is process-wide.

Failures that carry a stable code are thrown as UiMatchError. The CLI Reference lists the codes.

Selector plugins​

Set selectorsPlugin and, when required, selectors to use a selector resolver:

npx @uimatch/cli compare \
  figma=AbCdEf123:456-789 \
  story=http://localhost:6006 \
  selector=button-primary \
  selectors=.uimatch/anchors.json \
  selectorsPlugin=@uimatch/selector-anchors

Plugins execute as trusted code in the uiMatch process. See Plugin Development for the runtime contract and failure model.

Documentation​

License​

MIT

Namespaces​

Interfaces​

Type Aliases​

Variables​

Functions​