uiMatch Suite Skill

Purpose

Run a batch of visual comparisons defined in a JSON suite file and summarize overall results.

Use this skill to:

• execute multiple uiMatch comparisons in one go
• support CI-style checks locally
• see which components fail their quality gates across a suite

Environment / assumptions

• Run commands from the repository root.
• @uimatch/cli is installed as a devDependency.
• Playwright and Chromium are already installed:
  • npx playwright install chromium has been run previously.
• Node.js 20+ is available.

Figma token (IMPORTANT)

The uiMatch CLI does not load .env files automatically.
Before running any uimatch suite command:

export FIGMA_ACCESS_TOKEN="figd_..."

Suite items that rely on Figma API will fail if this is missing.

Figma references and quoting

Inside the suite JSON:

• Prefer FILE_KEY:NODE_ID format for figma fields:

  {
    "figma": "AbCdEf123:1-2"
  }
  

• If a full Figma URL is used, it is stored in JSON and not parsed by the shell directly, so shell escaping is less of a problem. Still, keep URLs valid and unbroken.

For more shared environment notes, see:

• ../_shared/uimatch-common-env.md

For advanced tuning (viewport, size, contentBasis, dpr) on suite items, see:

• ../_shared/uimatch-advanced-settings.md

Suite command usage

Basic command

npx uimatch suite \
  path=<PATH_TO_SUITE_JSON> \
  outDir=<OUTPUT_DIR> \
  concurrency=<NUMBER>

Recommended:

• outDir=.uimatch-suite
• concurrency=4

Example:

npx uimatch suite \
  path=.github/uimatch-suite.json \
  outDir=.uimatch-suite \
  concurrency=4

Suite file shape (high level)

A typical suite JSON looks like:

{
  "name": "Component Suite",
  "defaults": {
    "profile": "component/dev",
    "story": "http://localhost:6006"
  },
  "items": [
    {
      "name": "Button Primary",
      "figma": "AbCdEf123:1-2",
      "story": "http://localhost:6006/iframe.html?id=button--primary",
      "selector": "#storybook-root button"
    },
    {
      "name": "Card Component",
      "figma": "AbCdEf123:3-4",
      "story": "http://localhost:6006/iframe.html?id=card--default",
      "selector": "#storybook-root .card"
    }
  ]
}

For full schema details, see docs/docs/cli-reference.md (suite section).

Interpreting suite results

For each item, uiMatch will create a subdirectory under outDir:

• <outDir>/<item-slug>/figma.png
• <outDir>/<item-slug>/impl.png
• <outDir>/<item-slug>/diff.png
• <outDir>/<item-slug>/report.json

Claude Code should:

1. Enumerate all item directories under outDir.

2. For each report.json, read:

   • metrics.dfs
   • qualityGate.pass
   • qualityGate.reasons

3. Build a summary:

   • Which items passed
   • Which items failed (with reasons)
   • Any patterns across failures (e.g. all failing on color or spacing)

If CI-like behavior is desired, note that:

• uimatch suite will exit with:
  • 0 when all items pass
  • 1 when one or more items fail
  • 2 for configuration errors

When to use this skill

Use this skill when:

• The user already has (or is willing to create) a suite JSON file.
• They want to run multiple comparisons consistently (e.g. on every PR).
• They care about overall health of a component library or flow, not just one component.

For one-off comparisons, prefer the uimatch-compare skill. For text-only checks, prefer the uimatch-text-diff skill.