Skip to main content

Interface: CompareArgs

Defined in: packages/uimatch-cli/src/types/index.ts:292

UI comparison arguments

Properties​

align?​

optional align: "top" | "left" | "center" | "top-left";

Defined in: packages/uimatch-cli/src/types/index.ts:466

Alignment for pad/crop modes.

Default​

'center'

basicAuth?​

optional basicAuth: object;

Defined in: packages/uimatch-cli/src/types/index.ts:411

Basic authentication credentials for the target URL.

password​

password: string;

username​

username: string;

bootstrapExpectedFromFigma?​

optional bootstrapExpectedFromFigma: boolean;

Defined in: packages/uimatch-cli/src/types/index.ts:444

If true and expectedSpec is not provided, derive a minimal expectedSpec from Figma node JSON (REST) focusing on robust properties.

Default​

false

contentBasis?​

optional contentBasis: "union" | "intersection" | "figma" | "impl";

Defined in: packages/uimatch-cli/src/types/index.ts:482

Content basis mode for calculating pixelDiffRatioContent denominator.

  • union: Union of both content areas (default, can reach coverage=1.0 easily)
  • intersection: Intersection only (excludes padding-induced expansion)
  • figma: Figma's original content area
  • impl: Implementation's original content area

Default​

'union'

detectStorybookIframe?​

optional detectStorybookIframe: boolean;

Defined in: packages/uimatch-cli/src/types/index.ts:375

Whether to detect and use Storybook iframe for capture. When true, automatically switches to iframe content if Storybook URL is detected.

Default​

true

dpr?​

optional dpr: number;

Defined in: packages/uimatch-cli/src/types/index.ts:332

Device pixel ratio (for browser capture).

Default​

2

emitArtifacts?​

optional emitArtifacts: boolean;

Defined in: packages/uimatch-cli/src/types/index.ts:401

Whether to include PNG artifacts in the report.

expectedSpec?​

optional expectedSpec: ExpectedSpec;

Defined in: packages/uimatch-cli/src/types/index.ts:420

Expected style specification for comparison. Maps selectors to expected CSS properties.

figma​

figma: string;

Defined in: packages/uimatch-cli/src/types/index.ts:296

Figma reference (URL, fileKey:nodeId, or 'current' for selected node).

figmaAutoRoi?​

optional figmaAutoRoi: boolean;

Defined in: packages/uimatch-cli/src/types/index.ts:347

Enable automatic ROI detection from Figma child nodes. When true, if specified node is much larger than implementation capture, automatically finds closest matching child frame and uses it instead.

Default​

false

figmaChildStrategy?​

optional figmaChildStrategy: "area" | "area+position";

Defined in: packages/uimatch-cli/src/types/index.ts:321

Strategy for child-node mapping (when subselector is provided).

  • area: Match by size only
  • area+position: Match by size and relative position (default)

Default​

'area+position'

figmaScale?​

optional figmaScale: number;

Defined in: packages/uimatch-cli/src/types/index.ts:339

Figma image scale (separate from browser DPR). Allows independent control of Figma export resolution.

Default​

2

fontPreload?​

optional fontPreload: string[];

Defined in: packages/uimatch-cli/src/types/index.ts:406

Font URLs to preload.

ignore?​

optional ignore: string[];

Defined in: packages/uimatch-cli/src/types/index.ts:430

CSS properties to exclude from style comparison.

maxChildren?​

optional maxChildren: number;

Defined in: packages/uimatch-cli/src/types/index.ts:353

Maximum child elements to collect styles from.

Default​

200

maxDepth?​

optional maxDepth: number;

Defined in: packages/uimatch-cli/src/types/index.ts:368

Maximum depth to traverse for child elements.

Default​

6

padColor?​

optional padColor: 
  | "auto"
  | {
  b: number;
  g: number;
  r: number;
};

Defined in: packages/uimatch-cli/src/types/index.ts:472

Background color for padding ('auto' or RGB).

Default​

'auto'

pixelmatch?​

optional pixelmatch: object;

Defined in: packages/uimatch-cli/src/types/index.ts:385

pixelmatch sensitivity configuration (how visual differences are handled).

includeAA?​

optional includeAA: boolean;

Whether to include anti-aliasing in the comparison.

Default​
false

threshold?​

optional threshold: number;

Matching threshold (0 to 1). Smaller values make the comparison more sensitive.

Default​
0.1

projectRoot?​

optional projectRoot: string;

Defined in: packages/uimatch-cli/src/types/index.ts:494

Canonical project root used to constrain selector anchor file access. The CLI resolves this from projectRoot, the nearest git root, or cwd.

propsMode?​

optional propsMode: "default" | "extended" | "all";

Defined in: packages/uimatch-cli/src/types/index.ts:362

CSS properties to collect.

  • default: A curated list of common properties.
  • extended: default + additional layout and visual properties.
  • all: All computed styles.

Default​

'extended'

reuseBrowser?​

optional reuseBrowser: boolean;

Defined in: packages/uimatch-cli/src/types/index.ts:450

Reuse shared browser instance (recommended in /loop).

Default​

false

selector​

selector: string;

Defined in: packages/uimatch-cli/src/types/index.ts:306

CSS selector for the component root.

selectorPluginTimeoutMs?​

optional selectorPluginTimeoutMs: number;

Defined in: packages/uimatch-cli/src/types/index.ts:514

Validated selector plugin resolution deadline in milliseconds. Must be between 1 and Node.js's maximum timer delay (2,147,483,647). Programmatic callers may inject this instead of using the environment variable.

selectorsPath?​

optional selectorsPath: string;

Defined in: packages/uimatch-cli/src/types/index.ts:488

Path to selector anchors JSON (LLM-managed TODO/JSON). Enables automatic selector resolution and liveness checking.

selectorsPlugin?​

optional selectorsPlugin: string;

Defined in: packages/uimatch-cli/src/types/index.ts:507

Plugin module ID for selector resolution. Falls back to UIMATCH_SELECTORS_PLUGIN environment variable if not specified.

Default​

'@uimatch/selector-anchors'

selectorsWriteBack?​

optional selectorsWriteBack: boolean;

Defined in: packages/uimatch-cli/src/types/index.ts:500

Write back resolved selectors to anchors JSON.

Default​

false

sizeMode?​

optional sizeMode: "scale" | "strict" | "pad" | "crop";

Defined in: packages/uimatch-cli/src/types/index.ts:460

Size handling mode for dimension mismatches.

  • strict: Throw error on mismatch (default)
  • pad: Add letterboxing to smaller image
  • crop: Compare common region only
  • scale: Scale to match dimensions

Default​

'strict'

story​

story: string;

Defined in: packages/uimatch-cli/src/types/index.ts:301

Target URL (Storybook or any web page).

subselector?​

optional subselector: string;

Defined in: packages/uimatch-cli/src/types/index.ts:313

Optional child element inside selector for Figma child-node mapping. When provided, finds the best matching Figma child node based on size/position. Supports CSS, dompath, role, testid, and text selectors.

textCheck?​

optional textCheck: object;

Defined in: packages/uimatch-cli/src/types/index.ts:528

Figma ↔ Implementation text matching configuration. Validates that text content matches between design and implementation.

caseSensitive?​

optional caseSensitive: boolean;

Case-sensitive comparison (default: false)

enabled?​

optional enabled: boolean;

Enable text matching validation (default: false)

match?​

optional match: "exact" | "contains" | "ratio";

Matching mode: 'exact', 'contains' (Figma ⊆ Impl), or 'ratio' (similarity score) (default: 'ratio')

minRatio?​

optional minRatio: number;

Minimum similarity ratio for 'ratio' mode (default: 0.98)

mode?​

optional mode: "self" | "descendants";

Scope of text collection: 'self' (element only) or 'descendants' (element + children) (default: 'self')

normalize?​

optional normalize: "none" | "nfkc" | "nfkc_ws";

Normalization mode: 'none', 'nfkc', or 'nfkc_ws' (NFKC + whitespace collapse) (default: 'nfkc_ws')

Default​

{ enabled: false }

thresholds?​

optional thresholds: Thresholds;

Defined in: packages/uimatch-cli/src/types/index.ts:380

Acceptance thresholds.

tokens?​

optional tokens: TokenMap;

Defined in: packages/uimatch-cli/src/types/index.ts:425

Design token mappings (CSS variables to values).

verbose?​

optional verbose: boolean;

Defined in: packages/uimatch-cli/src/types/index.ts:521

Enable verbose logging (informational messages about mode, URLs, etc.). When false, only warnings and errors are shown.

Default​

false (quiet for programmatic use), true (CLI)

viewport?​

optional viewport: object;

Defined in: packages/uimatch-cli/src/types/index.ts:326

Viewport dimensions.

height​

height: number;

width​

width: number;

weights?​

optional weights: Partial<Record<
  | "color"
  | "border"
  | "spacing"
  | "radius"
  | "shadow"
  | "typography"
| "pixel", number>>;

Defined in: packages/uimatch-cli/src/types/index.ts:435

Category weights for DFS and future evaluation logic.